Skip to content
WunderUI

Number Field

Free

A field for a number that people type or step with plus and minus buttons, with limits, a step and a format for money, percentages and units.

npx wunderui-cli add number-field

Playground

Installation

bash
npx wunderui-cli add number-field

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Number Stepper for a small count that is changed by the buttons only, such as guests or items in a cart
  • Input for a number that is an identifier or has no range, such as a postcode or a phone number
  • Slider for a value in a range where the position matters more than the exact number

Format

The field shows the number in English format and reads what you type back into a number. Try 1,500 in the budget or 12.5 kg in the weight.

Step

The arrow keys and buttons change the value by one step. Shift with an arrow key takes a large step (10 by default) and Alt a small one (0.1), and at min or max the button dims and stops.

Changes by 5.

Label and message

Every field has a name: a visible label, or an aria-label where a column header already says it. A hint gives the rule before it is broken, and an error replaces it and turns the border red.

States

Hover and focus are real states: move the pointer over the field or press Tab. The border carries the focus, and a disabled field dims to 40 %.

Keyboard interactions

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

TaborShiftTab
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.
ArrowUporArrowDown
Raises or lowers the value by . At or it stops.
ShiftArrowUporShiftArrowDown
Steps by , 10 by default.
AltArrowUporAltArrowDown
Steps by , 0.1 by default.
HomeorEnd
Jumps to or to . 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 and motion

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

The figure marks the label above the field and the three parts of the field itself: the minus button, the input and the plus button inside one bordered frame.

  • 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.

  • data-slot="number-field"

    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.

  • data-slot="number-field-group"

    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.

  • data-slot="number-field-decrement"Optional

    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.

  • data-slot="number-field-input"

    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.

  • data-slot="number-field-increment"Optional

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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

    Don't leave the input without a name. The buttons have names; the input needs a label or an aria-label.

API reference

NumberField wraps the Base UI number field, so every part also takes the props of the primitive. The tables list the props you use most.

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.

PropTypeDefaultDescription
valuenumber | null—The number, for a controlled field, or for an empty one. Pair it with .
defaultValuenumber—The uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the prop instead.
onValueChange(value, eventDetails) => void—Called with the new number, or when the field is empty. It runs on every step and while typing, once the text is a valid number.
minnumber—The minimum value of the input element.
maxnumber—The maximum value of the input element.
stepnumber | "any"1Amount 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 prop explicitly in conjunction with this prop. S…
smallStepnumber0.1The step of Alt with an arrow key. Defaults to 0.1.
largeStepnumber10The step of Shift with an arrow key. Defaults to 10.
formatIntl.NumberFormatOptions—How the number is shown and read: the options of , such as , or .
localeIntl.LocalesArgument—The locale of the input element. Defaults to the user's runtime locale.
disabledbooleanfalseWhether the component should ignore user interaction.
readOnlybooleanfalseWhether the user should be unable to change the field value.
requiredbooleanfalseWhether the user must enter a value before submitting a form.
namestring—Identifies the field when a form is submitted.
idstring—The of the input, so that a with a matching names it.
allowOutOfRangebooleanfalseWhen true, direct text entry may be outside the / range without clamping, so native range underflow/overflow validation can occur. Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp.
allowWheelScrubbooleanfalseWhether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input.
snapOnStepbooleanfalseWhether the value should snap to the nearest step when incrementing or decrementing.
formstring—Identifies the form that owns the hidden input. Useful when the number field is rendered outside the form.
inputRefRef<HTMLInputElement>—A ref to access the hidden input element.
onValueCommitted(value, eventDetails) => void—Callback function that is fired when the value is committed. It runs later than , when: - The input is blurred after typing a value. - The pointer is released after scrubbing or pressing the increment/decrement buttons. It r…

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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the frame, for example to fill a column.

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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the minus button.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).

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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the input, for example for a longer value or to fill the frame.
aria-roledescriptionAriaAttributes["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 or to name the control.

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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the plus button.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("number-field")
Installnpx wunderui-cli add number-field

The full library index for assistants is at /llms.txt.