Klarhimmel UI
Klarhimmel ↗

Number field

Stable

A number you can type or step, with minus and plus buttons: the WAI-ARIA spin button.

npx shadcn add @klarhimmel/number-field @klarhimmel/input

When to use

  • Use for

    A quantity people may know or want to nudge: guests, nights, quantity.

  • Not for

    A rough value on a range. Use Slider. A choice among named options. Use Select.

  • Pairs with

    Field, a unit, a status line.

Preview

Up and Down add one, Page Up and Page Down add ten.

2 guests

number-field.tsx
import { Theme } from '@/components/klarhimmel/theme/style';
import { Field } from '@/components/klarhimmel/ui/input';
import { NumberField } from '@/components/klarhimmel/ui/number-field';

export default function Example() {
  return (
    <Theme theme="brand">
      <Field label="Guests">
        {(p) => <NumberField {...p} defaultValue={2} min={1} max={20} />}
      </Field>
    </Theme>
  );
}

Install

Import

import { NumberField } from '@/components/klarhimmel/ui/number-field';
Lands in
components/klarhimmel/ui/number-field.tsx, plus cn() and the theme item if they are missing. Import theme.css after Tailwind.
Render in
Render it inside <Theme>, once near the root of your app. Tokens and fonts are scoped to it, so outside it the component is unstyled.

Examples

  • Decimal

    kg

    Steps of a quarter kilo. Type 12,5 or 12.5.

    nights
    import { Field } from '@/components/klarhimmel/ui/input';
import { NumberField } from '@/components/klarhimmel/ui/number-field';

export default function NumberFieldDecimal() {
  return (
    <div className="flex w-[min(24rem,calc(100cqw-3rem))] flex-col gap-5">
      <Field label="Luggage weight" hint="Steps of a quarter kilo. Type 12,5 or 12.5.">
        {(p) => <NumberField {...p} defaultValue={12.5} step={0.25} min={0} max={32} unit="kg" />}
      </Field>
      <Field label="Nights">
        {(p) => <NumberField {...p} defaultValue={3} min={1} max={30} unit="nights" decreaseLabel="One night fewer" increaseLabel="One night more" />}
      </Field>
    </div>
  );
}

  • States

    The first Up goes to the minimum.

    At most two extra beds per room.

    import { Field } from '@/components/klarhimmel/ui/input';
import { NumberField } from '@/components/klarhimmel/ui/number-field';

export default function NumberFieldStates() {
  return (
    <div className="flex w-[min(24rem,calc(100cqw-3rem))] flex-col gap-5">
      <Field label="Rooms (empty)" hint="The first Up goes to the minimum.">
        {(p) => <NumberField {...p} min={1} max={10} />}
      </Field>
      <Field label="Extra beds" error="At most two extra beds per room.">
        {(p) => <NumberField {...p} defaultValue={3} max={3} invalid />}
      </Field>
      <Field label="Children (set by the room)">
        {(p) => <NumberField {...p} defaultValue={2} disabled />}
      </Field>
    </div>
  );
}

API reference

PropTypeDefaultDescription
value / defaultValue / onValueChangenumber | null / (value: number | null) => void-Controlled or uncontrolled. null means empty.
min / maxnumber-Limits for the keys, the buttons and typed text.
step / largeStepnumber1 / ten stepsWhat the arrows and the buttons add; what Page Up and Page Down add. The decimals of step set how many the field shows.
unitstring-Shown after the number and said with it (aria-valuetext).
namestring-Submits the number with a form (a hidden input).
invalid / disabledbooleanfalseError styling; switches it off.
decreaseLabel / increaseLabel / localestring'Decrease' / 'Increase' / 'en'The two buttons' names, and the language numbers are written in. Pass them translated.
aria-label / aria-labelledbystring-Needed when no Field or <label htmlFor> names it.
classNamestring-Extra classes, merged after the component's own.

Accessibility

KeyDoes
Up / DownAdd or subtract the step; from empty, Up goes to the minimum
Page Up / Page DownAdd or subtract ten steps (or largeStep)
Home / EndJump to the minimum or the maximum, when there is one
Enter / leaving the fieldReads what was typed, inside the limits; a non-number is put back

The WAI-ARIA spin button. The buttons are for the pointer and are not tab stops: the keyboard has the arrow keys. A decimal comma is accepted.

Accessibility