# Number Field

A numeric input with increment/decrement buttons.

- Category: Forms
- Page: https://wunderui.com/components/number-field
- Tier: Free

## Install

```bash
npx wunderui-cli add number-field
```

## Import

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

## Minimal usage

Then use it:

```tsx
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

export function Quantity() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="quantity">Quantity</Label>
      <NumberField id="quantity" defaultValue={12} min={1} max={50}>
        <NumberFieldGroup>
          <NumberFieldDecrement aria-label="Decrease quantity" />
          <NumberFieldInput />
          <NumberFieldIncrement aria-label="Increase quantity" />
        </NumberFieldGroup>
      </NumberField>
    </div>
  )
}
```

Expected result: You see the label Quantity above a white field with a minus button, the number 12 and a plus button. Clicking the label focuses the number, and End jumps to 50 and dims the plus button.

## Usage

```tsx
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="quantity">Quantity</Label>
      <NumberField id="quantity" defaultValue={12} min={1} max={50}>
        <NumberFieldGroup>
          <NumberFieldDecrement aria-label="Decrease quantity" />
          <NumberFieldInput />
          <NumberFieldIncrement aria-label="Increase quantity" />
        </NumberFieldGroup>
      </NumberField>
    </div>
  )
}
```

## When to use

### Use Number Field for

- A quantity, a number of seats or a threshold that people type or step, with a known range
- A value with a format, such as money, a percentage or a number with a unit
- A number in a form that is read back, so it needs a label, a hint and an error

### Use something else

- [Number Stepper](https://wunderui.com/components/number-stepper) for a small count that is changed by the buttons only, such as guests or items in a cart
- [Input](https://wunderui.com/components/input) for a number that is an identifier or has no range, such as a postcode or a phone number
- [Slider](https://wunderui.com/components/slider) for a value in a range where the position matters more than the exact number

## Keyboard

The input is a text field that knows numbers. Arrow keys step the value; Shift and Alt change the step size.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the input and out of it. The plus and minus buttons are not tab stops: the keyboard path is the arrow keys in the input. A disabled field is skipped. |
| `ArrowUp` or `ArrowDown` | Raises or lowers the value by `step`. At `min` or `max` it stops. |
| `Shift+ArrowUp` or `Shift+ArrowDown` | Steps by `largeStep`, 10 by default. |
| `Alt+ArrowUp` or `Alt+ArrowDown` | Steps by `smallStep`, 0.1 by default. |
| `Home` or `End` | Jumps to `min` or to `max`. It only works when that limit is set. |
| `0–9` | Types a number. Letters and other characters are not taken, and the formatted text is read back into a number when you leave the field. |

## Behavior

What the field does with its value, its limits, errors and motion.

- **Value or null:** The change handler gets a number, or null when the field is empty. The field never turns an empty input into 0.
- **Format and locale:** The format takes Intl.NumberFormat options such as currency, percent or unit. Text follows the locale and is read back when you leave the field, and a percent is a fraction: 0.15 shows as 15%.
- **Limits:** A typed value outside the limits is corrected when you leave the field; arrow keys and buttons never pass them. Allow out-of-range values if you want to report them yourself.
- **Buttons at the edge:** At the minimum the minus button and at the maximum the plus button are disabled and dim to 40%. The buttons are for the pointer and are not tab stops; the keyboard uses the arrow keys.
- **Error:** Set aria-invalid on the input and the frame turns red, with a red focus ring. Put the message in an element and point aria-describedby at it; the white fill stays.
- **Disabled and read-only:** Disabled dims the whole frame to 40% and takes it out of the tab order. A read-only field cannot be stepped, its buttons are disabled, and the frame dims the same way.
- **Width:** The group is as wide as its parts: 36 px per button and 64 px for the input. Give the input a width class for longer values, or make the group full width to fill a column.
- **Scroll wheel:** The wheel does not change the value. Turn on wheel scrubbing to let it change the value while the field is focused and the pointer is over it.
- **Motion:** The border and the button fills change colour quickly. Nothing moves.
- **Reduced motion:** There is no movement to remove, so reduced motion changes nothing. The colour changes stay.

## Anatomy

- `Label`: The visible name of the field: a Label whose htmlFor matches the NumberField id, so a click on it focuses the input. A field with no room for a label takes an aria-label on the input.
- `NumberField`: The root. It holds the number (null when empty), the limits, the steps and the format, and it has no element of its own; its id goes on the input.
- `NumberFieldGroup`: The bordered frame around the buttons and input: 36 px high, 8 px corner, 1 px dividers. It carries the hover border, the indigo focus ring and the red error state.
- `NumberFieldDecrement`: The minus button on the left, 36 px wide. It lowers the value by one step and dims at the minimum; its default name is Decrease, so name it after what it changes.
- `NumberFieldInput`: The text input, 64 px wide by default with the number centred. It accepts only number characters, formats on blur and answers arrow keys, Home and End.
- `NumberFieldIncrement`: The plus button on the right, 36 px wide. It raises the value by one step and dims at the maximum, and its default name is Increase.

## Best practices

### Do

- Give the field a visible label joined by htmlFor and the NumberField id. Where a column header already names it, put an aria-label on the input.
- Set min, max and step to the real limits, such as 1 to 50. The buttons stop at the edges and Home and End jump to them.
- Name the buttons after what they change, such as Add a seat and Remove a seat. The defaults, Increase and Decrease, do not say what grows.
- Put the unit in the format (for example kilograms) or in the label, so the number is never read without it. Widen the input when the formatted text is longer than 64 px.
- Treat the value as a number or null. A field the person emptied reports null, not 0; show an error under it and mark the input invalid.

### Don't

- Don't use it for a number nobody steps in small amounts, such as a year or a phone number. Use an Input with a numeric keyboard.
- Don't use it for a count of one to ten where there is no typing. Number Stepper is a smaller control for that.
- Don't leave the input without a name. The buttons have names; the input needs a label or an aria-label.

## API reference

### NumberField

| Prop | Type | Default | Description |
|---|---|---|---|
| allowOutOfRange | boolean | false | When true, direct text entry may be outside the `min`/`max` range without clamping, so native range underflow/overflow validation can occur. Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp. |
| allowWheelScrub | boolean | false | Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultValue | number |  | The uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the `value` prop instead. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| form | string |  | Identifies the form that owns the hidden input. Useful when the number field is rendered outside the form. |
| format | Intl.NumberFormatOptions |  | How the number is shown and read: the options of `Intl.NumberFormat`, such as `{ style: "currency", currency: "USD" }`, `{ style: "percent" }` or `{ style: "unit", unit: "kilogram" }`. |
| id | string |  | The `id` of the input, so that a `Label` with a matching `htmlFor` names it. |
| inputRef | React.Ref<HTMLInputElement> |  | A ref to access the hidden input element. |
| largeStep | number | 10 | The step of Shift with an arrow key. Defaults to 10. |
| locale | Intl.LocalesArgument |  | The locale of the input element. Defaults to the user's runtime locale. |
| max | number |  | The maximum value of the input element. |
| min | number |  | The minimum value of the input element. |
| name | string |  | Identifies the field when a form is submitted. |
| onValueChange | ((value: number \| null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void) |  | Called with the new number, or `null` when the field is empty. It runs on every step and while typing, once the text is a valid number. |
| onValueCommitted | ((value: number \| null, eventDetails: NumberFieldRoot.CommitEventDetails) => void) |  | Callback function that is fired when the value is committed. It runs later than `onValueChange`, when: - The input is blurred after typing a value. - The pointer is released after scrubbing or pressing the increment/decrement buttons. It r… |
| readOnly | boolean | false | Whether the user should be unable to change the field value. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| required | boolean | false | Whether the user must enter a value before submitting a form. |
| smallStep | number | 0.1 | The step of Alt with an arrow key. Defaults to 0.1. |
| snapOnStep | boolean | false | Whether the value should snap to the nearest step when incrementing or decrementing. |
| step | number \| 'any' | 1 | Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop. S… |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| value | number \| null |  | The number, for a controlled field, or `null` for an empty one. Pair it with `onValueChange`. |

Also accepts React.HTMLAttributes attributes.

### NumberFieldDecrement

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the minus button. |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

### NumberFieldGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the frame, for example `w-full` to fill a column. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### NumberFieldIncrement

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the plus button. |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

### NumberFieldInput

| Prop | Type | Default | Description |
|---|---|---|---|
| aria-roledescription | React.AriaAttributes['aria-roledescription'] | 'Number field' | A user-friendly description of the input's role for assistive tech. This is a role description, not an accessible name — use `Field.Label` or `aria-label` to name the control. |
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the input, for example `w-24` for a longer value or `flex-1 min-w-0` to fill the frame. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.InputHTMLAttributes attributes.

## Examples

### Format: number, currency, percent and unit

```tsx
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="quantity">Quantity</Label>
      <NumberField id="quantity" defaultValue={12} min={1} max={50}>
        <NumberFieldGroup>
          <NumberFieldDecrement aria-label="Decrease quantity" />
          <NumberFieldInput />
          <NumberFieldIncrement aria-label="Increase quantity" />
        </NumberFieldGroup>
      </NumberField>
    </div>
  )
}
```

### Step: one step, a large step, decimals and a maximum

```tsx
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="seats">Seats</Label>
      <NumberField id="seats" defaultValue={25} min={0} max={100} step={5}>
        <NumberFieldGroup>
          <NumberFieldDecrement aria-label="Decrease seats" />
          <NumberFieldInput aria-describedby="seats-hint" />
          <NumberFieldIncrement aria-label="Increase seats" />
        </NumberFieldGroup>
      </NumberField>
      <p id="seats-hint" className="text-xs text-text-tertiary">Changes by 5.</p>
    </div>
  )
}
```

### Label and message: label, hint, error and no visible label

```tsx
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="qty-label">Quantity</Label>
      <NumberField id="qty-label" defaultValue={12} min={1} max={50}>
        <NumberFieldGroup>
          <NumberFieldDecrement aria-label="Decrease quantity" />
          <NumberFieldInput />
          <NumberFieldIncrement aria-label="Increase quantity" />
        </NumberFieldGroup>
      </NumberField>
    </div>
  )
}
```

### States: rest, hover, focus, at max and disabled

```tsx
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

export function Example() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="qty-state">Quantity</Label>
      <NumberField id="qty-state" defaultValue={12} min={1} max={50}>
        <NumberFieldGroup>
          <NumberFieldDecrement aria-label="Decrease quantity" />
          <NumberFieldInput />
          <NumberFieldIncrement aria-label="Increase quantity" />
        </NumberFieldGroup>
      </NumberField>
    </div>
  )
}
```

## In context

### Seats: a quantity that sets a price

Type a number or step it with the buttons; the monthly total follows at once and is announced politely. The buttons are named after what they change.

```tsx
import { useState } from "react"
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

const PRICE_PER_SEAT = 12

export function Example() {
  const [seats, setSeats] = useState<number | null>(5)
  const total = (seats ?? 0) * PRICE_PER_SEAT

  return (
    <div className="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <div className="flex flex-col gap-2">
        <Label htmlFor="seats">Seats</Label>
        <NumberField id="seats" value={seats} onValueChange={setSeats} min={1} max={50}>
          <NumberFieldGroup>
            <NumberFieldDecrement aria-label="Remove a seat" />
            <NumberFieldInput aria-describedby="seats-hint" />
            <NumberFieldIncrement aria-label="Add a seat" />
          </NumberFieldGroup>
        </NumberField>
        <p id="seats-hint" className="text-xs text-text-tertiary">
          Between 1 and 50 seats.
        </p>
      </div>
      <div className="flex items-baseline justify-between border-t border-border pt-4">
        <span className="text-sm text-text-secondary">Monthly total</span>
        <span aria-live="polite" className="text-lg font-semibold tabular-nums text-foreground">
          {total.toLocaleString("en-US", { style: "currency", currency: "USD" })}
        </span>
      </div>
    </div>
  )
}
```

### Parcel size: fields that carry their own unit

Each field formats its own unit, and the weight takes one decimal. The three fields sit in one row from 640 px and stack below.

```tsx
import { Label } from "@/components/ui/label"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

const FIELDS = [
  { id: "weight", label: "Weight", noun: "weight", start: 2.4, step: 0.1, max: 30, unit: "kilogram" },
  { id: "length", label: "Length", noun: "length", start: 40, step: 1, max: 120, unit: "centimeter" },
  { id: "width", label: "Width", noun: "width", start: 30, step: 1, max: 120, unit: "centimeter" },
]

export function Example() {
  return (
    <form className="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card p-4">
      <h3 className="text-sm font-semibold text-foreground">Parcel size</h3>
      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
        {FIELDS.map((field) => (
          <div key={field.id} className="flex flex-col gap-2">
            <Label htmlFor={field.id}>{field.label}</Label>
            <NumberField
              id={field.id}
              name={field.id}
              defaultValue={field.start}
              min={0}
              max={field.max}
              step={field.step}
              format={{ style: "unit", unit: field.unit, unitDisplay: "short", maximumFractionDigits: 1 }}
              locale="en-US"
            >
              <NumberFieldGroup className="w-full">
                <NumberFieldDecrement aria-label={`Decrease ${field.noun}`} />
                <NumberFieldInput className="w-0 min-w-0 flex-1" />
                <NumberFieldIncrement aria-label={`Increase ${field.noun}`} />
              </NumberFieldGroup>
            </NumberField>
          </div>
        ))}
      </div>
    </form>
  )
}
```

### Usage alert: a field inside a sentence

The sentence is the label of the field. Clear the field to see the error; a value outside 10% to 100% is corrected when you leave it.

```tsx
import { useState } from "react"
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from "@/components/ui/number-field"

export function Example() {
  const [threshold, setThreshold] = useState<number | null>(0.8)
  const invalid = threshold === null

  return (
    <div className="flex w-full max-w-md flex-col gap-2">
      <div className="flex flex-wrap items-center gap-x-2 gap-y-2 text-sm text-foreground">
        <span id="alert-label">Email me when usage reaches</span>
        <NumberField
          value={threshold}
          onValueChange={setThreshold}
          min={0.1}
          max={1}
          step={0.05}
          largeStep={0.1}
          format={{ style: "percent" }}
          locale="en-US"
        >
          <NumberFieldGroup>
            <NumberFieldDecrement aria-label="Lower the threshold" />
            <NumberFieldInput className="w-20" aria-labelledby="alert-label" aria-invalid={invalid} aria-describedby="alert-error" />
            <NumberFieldIncrement aria-label="Raise the threshold" />
          </NumberFieldGroup>
        </NumberField>
        <span>of the plan limit</span>
      </div>
      <p id="alert-error" role="alert" className="min-h-4 text-xs text-tint-text-red">
        {invalid ? "Enter a percentage from 10% to 100%." : null}
      </p>
    </div>
  )
}
```

## For AI agents

`get_component("number-field")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
