Number Field

Seats

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldDemo() {
  return (
    <NumberField
      className="w-full max-w-48"
      label="Seats"
      defaultValue={5}
      minValue={1}
      maxValue={50}
    />
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/number-field

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { NumberField } from "@/components/ui/number-field";

tsx

<NumberField label="Quantity" name="quantity" defaultValue={1} minValue={0} />

The value is always a number. The field formats it for display with formatOptions and the user's locale, parses what the user types, and on blur clamps it to minValue / maxValue and snaps it to step.

An empty field is NaN

When the user clears the input, onChange receives NaN, not 0 or null. Check with Number.isNaN(value) before doing arithmetic, and use isRequired if an empty value isn't allowed.

When to use

Number Field — quantities, prices, percentages, measurements: any value that is really a number and benefits from steppers, formatting or a range.
Slider — picking an approximate value in a range, where the exact number matters less than its position.
Text Field — number-like strings that aren't quantities: phone numbers, postal codes, card numbers, IDs. Use inputMode="numeric" there.
Input OTP — one-time verification codes.

Anatomy

tsx

<NumberField>              {/* root: <div>, owns the number value and validation */}
  <Label />                {/* from `label` */}
  <FieldGroup>             {/* role="group": the visible box */}
    <Button slot="decrement" />  {/* stepper="split" only */}
    <FieldInput />               {/* the text <input> */}
    <Button slot="increment" />  {/* stepper="split" only */}
    <div>                        {/* stepper="stacked" only */}
      <Button slot="increment" />
      <Button slot="decrement" />
    </div>
  </FieldGroup>
  <Description />          {/* from `description` */}
  <FieldError />           {/* shown only while invalid */}
</NumberField>

Part	Renders	Notes
`NumberField`	`<div>`	Root. Carries `data-slot="number-field"`, the `group/field` class and all state attributes.
`Label`	`<label>`	Rendered when `label` is set.
`FieldGroup`	`<div role="group">`	The visible box. Groups the input and steppers for assistive technology.
`FieldInput`	`<input type="text">`	Shows the formatted value. `inputMode` is chosen from `minValue` and the format so the right mobile keyboard appears.
Increment / decrement	`<button>`	Chevrons (`stacked`) or plus/minus (`split`). Labelled "Increase …" / "Decrease …", excluded from the tab order, disabled at the bounds. Hold to repeat.
`Description`	`<span slot="description">`	Rendered when `description` is set.
`FieldError`	`<span slot="errorMessage">`	Rendered only while invalid.
Hidden `<input>`	`<input type="hidden">`	Rendered when `name` is set. Submits the raw number, not the formatted text.

Examples

Variants

outline (default), filled for dense or tinted surfaces, and underlined for minimal forms. The same variants apply to every field component.

outline

filled

underlined

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldVariants() {
  return (
    <div className="flex w-full max-w-48 flex-col gap-5">
      {(["outline", "filled", "underlined"] as const).map((variant) => (
        <NumberField
          key={variant}
          variant={variant}
          label={variant}
          defaultValue={8}
          className="capitalize"
        />
      ))}
    </div>
  );
}

Sizes

sm (28px), md (32px, default) and lg (40px), matching the buttons and other fields.

Small

Medium

Large

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldSizes() {
  return (
    <div className="flex w-full max-w-48 flex-col gap-5">
      <NumberField size="sm" label="Small" defaultValue={2} />
      <NumberField size="md" label="Medium" defaultValue={2} />
      <NumberField size="lg" label="Large" stepper="split" defaultValue={2} />
    </div>
  );
}

Stepper layouts

stepper="stacked" (default) puts compact chevrons on the right. split puts larger − and + buttons on either side, which suits touch and quantity pickers. none hides the buttons; the arrow keys and scroll wheel still work.

Stacked

Default. Compact, right-aligned.

Split

Bigger targets for touch.

None

Keyboard and wheel only.

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldSteppers() {
  return (
    <div className="flex w-full max-w-48 flex-col gap-5">
      <NumberField
        label="Stacked"
        stepper="stacked"
        defaultValue={3}
        minValue={0}
        description="Default. Compact, right-aligned."
      />
      <NumberField
        label="Split"
        stepper="split"
        defaultValue={3}
        minValue={0}
        description="Bigger targets for touch."
      />
      <NumberField
        label="None"
        stepper="none"
        defaultValue={3}
        minValue={0}
        description="Keyboard and wheel only."
      />
    </div>
  );
}

Formatting

formatOptions takes any Intl.NumberFormat option: currency, percent, units, fraction digits, sign display, grouping. Users can type in their locale's format, including the currency symbol or percent sign. Percent values are fractions: 0.15 displays as 15%.

Price

Discount

Distance

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldFormatting() {
  return (
    <div className="flex w-full max-w-52 flex-col gap-5">
      <NumberField
        label="Price"
        defaultValue={49.99}
        formatOptions={{ style: "currency", currency: "USD" }}
      />
      <NumberField
        label="Discount"
        defaultValue={0.15}
        minValue={0}
        maxValue={1}
        step={0.05}
        formatOptions={{ style: "percent" }}
      />
      <NumberField
        label="Distance"
        defaultValue={12}
        formatOptions={{
          style: "unit",
          unit: "kilometer",
          unitDisplay: "short",
        }}
      />
    </div>
  );
}

Range and step

minValue and maxValue bound the value; the steppers disable at each end. step sets the increment, and typed values snap to the nearest step (counted from minValue) on blur. Fractional steps work with any format.

Team size

Between 1 and 20 seats.

Time logged

Snaps to 15-minute steps.

Temperature offset

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldRange() {
  return (
    <div className="flex w-full max-w-52 flex-col gap-5">
      <NumberField
        label="Team size"
        defaultValue={5}
        minValue={1}
        maxValue={20}
        description="Between 1 and 20 seats."
      />
      <NumberField
        label="Time logged"
        defaultValue={1.5}
        minValue={0}
        maxValue={24}
        step={0.25}
        formatOptions={{
          style: "unit",
          unit: "hour",
          unitDisplay: "long",
          minimumFractionDigits: 2,
        }}
        description="Snaps to 15-minute steps."
      />
      <NumberField
        label="Temperature offset"
        defaultValue={-2}
        minValue={-10}
        maxValue={10}
        formatOptions={{
          style: "unit",
          unit: "celsius",
          signDisplay: "exceptZero",
        }}
      />
    </div>
  );
}

Disabled and read only

isDisabled disables the input and steppers. isReadOnly keeps the formatted value focusable and selectable but blocks edits and stepping.

Seats

Contact sales to change seats on Enterprise.

Monthly price

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldDisabled() {
  return (
    <div className="flex w-full max-w-52 flex-col gap-5">
      <NumberField
        label="Seats"
        defaultValue={25}
        isDisabled
        description="Contact sales to change seats on Enterprise."
      />
      <NumberField
        label="Monthly price"
        defaultValue={240}
        isReadOnly
        formatOptions={{ style: "currency", currency: "USD" }}
      />
    </div>
  );
}

Controlled

value and onChange let you derive UI from the number, like a live total. onChange fires when the value is committed (on blur, Enter or a step), not on every keystroke.

Seats

Total: $60.00 / month

import { useState } from "react";
import { NumberField } from "@/components/ui/number-field";

const pricePerSeat = 12;
const currency = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
});

export default function NumberFieldControlled() {
  const [seats, setSeats] = useState(5);
  return (
    <div className="flex w-full max-w-56 flex-col gap-3">
      <NumberField
        label="Seats"
        stepper="split"
        minValue={1}
        maxValue={100}
        value={seats}
        onChange={setSeats}
      />
      <p className="text-muted-foreground text-sm">
        {Number.isNaN(seats) ? (
          "Enter a number of seats."
        ) : (
          <>
            Total:{" "}
            <span className="font-medium text-foreground tabular-nums">
              {currency.format(seats * pricePerSeat)}
            </span>{" "}
            / month
          </>
        )}
      </p>
    </div>
  );
}

Required and range validation

By default an out-of-range value is clamped on blur. Set commitBehavior="validate" to keep what the user typed and show a range error instead, so they notice the limit. With native validation, the form won't submit until the field is valid.

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldValidation() {
  return (
    <Form
      className="flex w-full max-w-56 flex-col gap-4"
      onSubmit={(e) => e.preventDefault()}
    >
      <NumberField
        label="Guests"
        name="guests"
        isRequired
        minValue={1}
        maxValue={8}
        commitBehavior="validate"
        description="Up to 8 guests per booking."
      />
      <Button type="submit" className="self-start">
        Book table
      </Button>
    </Form>
  );
}

Custom validation

validate receives the parsed number (NaN when empty) and returns an error string or null. With validationBehavior="aria" on the Form, errors show live.

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldCustomValidation() {
  return (
    <Form
      className="flex w-full max-w-56 flex-col gap-4"
      validationBehavior="aria"
      onSubmit={(e) => e.preventDefault()}
    >
      <NumberField
        label="Batch size"
        name="batch"
        defaultValue={48}
        minValue={8}
        maxValue={512}
        step={8}
        description="A multiple of 8 between 8 and 512."
        validate={(value) =>
          value > 256 ? "Batches over 256 need a GPU plan." : null
        }
      />
      <Button type="submit" className="self-start">
        Start training
      </Button>
    </Form>
  );
}

Form submission

Set name and the raw number is submitted through a hidden input: 1500, not €1,500.00, and 0.1, not 10%. An empty field submits an empty string.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldForm() {
  const [data, setData] = useState<Record<string, FormDataEntryValue> | null>(
    null,
  );
  return (
    <Form
      className="flex w-full max-w-56 flex-col gap-4"
      onSubmit={(e) => {
        e.preventDefault();
        setData(Object.fromEntries(new FormData(e.currentTarget)));
      }}
    >
      <NumberField
        label="Budget"
        name="budget"
        defaultValue={1500}
        minValue={0}
        formatOptions={{ style: "currency", currency: "EUR" }}
      />
      <NumberField
        label="Discount"
        name="discount"
        defaultValue={0.1}
        minValue={0}
        maxValue={1}
        step={0.05}
        formatOptions={{ style: "percent" }}
      />
      <Button type="submit" className="self-start">
        Save
      </Button>
      {data && (
        <code className="rounded-md bg-muted px-2 py-1 text-xs">
          {JSON.stringify(data)}
        </code>
      )}
    </Form>
  );
}

Recipes

Cart quantities

Small split steppers in a line-item list, each with an aria-label that names the product, driving a live subtotal.

Heavyweight tee
Sand / M · $38.00
Six-panel cap
Olive · $29.00
Canvas tote
Natural · $24.00

Subtotal$129.00

import { Trash2Icon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { NumberField } from "@/components/ui/number-field";

const currency = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
});

const initial = [
  {
    id: "tee",
    name: "Heavyweight tee",
    variant: "Sand / M",
    price: 38,
    qty: 2,
  },
  { id: "cap", name: "Six-panel cap", variant: "Olive", price: 29, qty: 1 },
  { id: "tote", name: "Canvas tote", variant: "Natural", price: 24, qty: 1 },
];

export default function NumberFieldRecipeCart() {
  const [lines, setLines] = useState(initial);
  const subtotal = lines.reduce(
    (sum, l) => sum + l.price * (Number.isNaN(l.qty) ? 0 : l.qty),
    0,
  );
  return (
    <div className="w-full max-w-md rounded-xl border bg-card">
      <ul className="divide-y">
        {lines.map((line) => (
          <li key={line.id} className="flex items-center gap-3 p-4">
            <div className="min-w-0 flex-1">
              <p className="truncate font-medium text-sm">{line.name}</p>
              <p className="text-muted-foreground text-xs">
                {line.variant} · {currency.format(line.price)}
              </p>
            </div>
            <NumberField
              aria-label={`Quantity of ${line.name}`}
              size="sm"
              stepper="split"
              minValue={1}
              maxValue={10}
              value={line.qty}
              onChange={(qty) =>
                setLines((ls) =>
                  ls.map((l) => (l.id === line.id ? { ...l, qty } : l)),
                )
              }
              className="w-28 shrink-0"
            />
            <Button
              size="icon-sm"
              variant="ghost"
              aria-label={`Remove ${line.name}`}
              onPress={() =>
                setLines((ls) => ls.filter((l) => l.id !== line.id))
              }
            >
              <Trash2Icon />
            </Button>
          </li>
        ))}
      </ul>
      <div className="flex items-center justify-between border-t p-4 text-sm">
        <span className="text-muted-foreground">Subtotal</span>
        <span className="font-semibold tabular-nums">
          {currency.format(subtotal)}
        </span>
      </div>
    </div>
  );
}

Resource limits

A settings list where each field is labelled by its row title via aria-labelledby, with unit formatting and per-row ranges.

Memory

RAM available to each instance.

Max instances

Upper bound for autoscaling.

Request timeout

Requests running longer are cancelled.

import { NumberField } from "@/components/ui/number-field";

const limits = [
  {
    id: "memory",
    title: "Memory",
    description: "RAM available to each instance.",
    defaultValue: 2,
    minValue: 0.5,
    maxValue: 16,
    step: 0.5,
    formatOptions: { style: "unit", unit: "gigabyte" },
  },
  {
    id: "instances",
    title: "Max instances",
    description: "Upper bound for autoscaling.",
    defaultValue: 4,
    minValue: 1,
    maxValue: 50,
    step: 1,
  },
  {
    id: "timeout",
    title: "Request timeout",
    description: "Requests running longer are cancelled.",
    defaultValue: 30,
    minValue: 1,
    maxValue: 900,
    step: 5,
    formatOptions: { style: "unit", unit: "second", unitDisplay: "short" },
  },
] satisfies {
  id: string;
  title: string;
  description: string;
  defaultValue: number;
  minValue: number;
  maxValue: number;
  step: number;
  formatOptions?: Intl.NumberFormatOptions;
}[];

export default function NumberFieldRecipeLimits() {
  return (
    <div className="w-full max-w-lg divide-y rounded-xl border bg-card">
      {limits.map(({ id, title, description, ...field }) => (
        <div key={id} className="flex items-center justify-between gap-6 p-4">
          <div>
            <p id={`${id}-label`} className="font-medium text-sm">
              {title}
            </p>
            <p className="text-muted-foreground text-xs">{description}</p>
          </div>
          <NumberField
            aria-labelledby={`${id}-label`}
            size="sm"
            className="w-32 shrink-0"
            {...field}
          />
        </div>
      ))}
    </div>
  );
}

Accessibility

The input is a text field with aria-roledescription="number field", so screen readers announce it as a number field along with its formatted value.
The input and steppers are wrapped in a role="group" labelled by the field label.
Stepper buttons are named "Increase Seats" / "Decrease Seats" from the label (override with incrementAriaLabel / decrementAriaLabel). They're skipped in the tab order because the arrow keys do the same job.
Values are formatted and parsed with the user's locale, including their decimal and grouping separators and numbering system.
inputMode is set automatically (numeric, decimal or text) so mobile keyboards include a minus sign or decimal point only when needed.
The scroll wheel steps the value only while the field has focus. Disable it with isWheelDisabled in scrollable layouts.

Keyboard

Key	Action
`↑` / `↓`	Increments / decrements by `step`
`Page Up` / `Page Down`	Increments / decrements by `step`
`Home` / `End`	Sets the value to `minValue` / `maxValue`, when set
`Enter`	Commits the typed value (parse, clamp, snap and format)

Styling

Data attributes

On the NumberField root. Children can react with group-data-*/field: variants.

Attribute	Present when
`data-disabled`	`isDisabled` is true
`data-readonly`	`isReadOnly` is true
`data-required`	`isRequired` is true
`data-invalid`	Validation failed, or `isInvalid` is true

On the FieldGroup: data-hovered, data-focus-within, data-focus-visible, data-invalid and data-disabled. On each stepper button: data-hovered, data-pressed, data-disabled (at a bound) and data-focus-visible.

Slots

`data-slot`	Element
`number-field`	Root
`label`, `description`, `field-error`	Field text
`field-group`	Visible box
`field-input`	`<input>`

The input uses tabular-nums so digits don't shift while stepping. The box styles come from fieldVariants in field.tsx; see Text Field.

Render props

className also accepts a function of the field state, which includes the live state (numberValue, canIncrement, canDecrement):

tsx

<NumberField
  label="Balance"
  className={({ state }) => (state.numberValue < 0 ? "text-destructive" : "")}
/>

API Reference

NumberField

Prop

Type

Also accepts every prop of React Aria's NumberField.

Slider — for approximate values in a range.
Text Field — for number-like strings, and the shared field building blocks.
Select — shares the same field variants and sizes.