Number Field

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add number-field

Usage#

import {
  NumberField,
  NumberFieldGroup,
  NumberFieldInput,
  NumberFieldIncrement,
  NumberFieldDecrement,
} from "@/components/ui/number-field"
import { Field, FieldLabel } from "@/components/ui/field"

export function Example() {
  return (
    <Field>
      <FieldLabel>Seats</FieldLabel>
      <NumberField defaultValue={5} min={1} max={50}>
        <NumberFieldGroup>
          <NumberFieldInput />
          <NumberFieldDecrement />
          <NumberFieldIncrement />
        </NumberFieldGroup>
      </NumberField>
    </Field>
  )
}

Anatomy#

Every part but the group and the input is optional. Order the steppers however you like: trailing, or one on each side.

<NumberField>
  <NumberFieldScrubArea>
    <FieldLabel />
    <NumberFieldScrubAreaCursor />
  </NumberFieldScrubArea>
  <NumberFieldGroup>
    <NumberFieldDecrement />
    <NumberFieldInput />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>

Basic#

The value is a number, never a string. Type, press the arrow keys, or press the steppers. Hold a stepper and it repeats after a short pause.

Min, max and step#

Steps clamp to min and max, and a typed value clamps on blur. The stepper at a bound disables itself. Shift and PageUp/PageDown take largeStep, Alt takes smallStep, and Home/End jump to the bounds.

Formatting#

Pass Intl.NumberFormatOptions to format. Typed text is read back in the same locale, so 1.299,50 € and $1,299.50 both parse. A percent field stores the fraction: 25% is 0.25.

Scrub area#

Wrap the label in NumberFieldScrubArea and drag it. With a mouse the pointer locks, so the drag never runs off screen, and NumberFieldScrubAreaCursor draws the cursor in its place. Safari keeps the native resize cursor instead.

Quantity#

Put the steppers on either side and center the figure for a cart or a guest count.

Field#

Inside a Field, the label, the description and the error state wire themselves: FieldLabel names the input, FieldHint describes it, and hasError turns the frame destructive.

Input group#

NumberFieldGroup is an Input frame, so InputGroup strips it into a segment. Keep NumberField outside the group and the group's size reaches the field.

Sizes#

The same three heights as Input: sm (32 px), md (36 px) and lg (40 px), set on NumberFieldGroup. Unset, it follows the container (a Form imposes lg) or the density (sm under compact, md under comfortable). The steppers scale with it.

Disabled and read-only#

disabled dims the field and drops it from the form. readOnly keeps it focusable and readable but fixes the value, so the steppers and the keys do nothing.

Controlled#

onValueChange fires on every keystroke and step. onValueCommitted fires once the change settles, which is the one to save on.

API reference#

FAQ#