Number field

A numeric input element with increment and decrement buttons, and a scrub area.

Preview

Amount

Installation

Install the local ghost-kit source bundle while the registry runs at localhost:3110. It contains this component and its source dependencies. Prepare the local registry first so token dependencies also resolve locally.

Install

npx shadcn@latest add http://localhost:3110/r/ghost-kit.json

Basic usage

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

<NumberField.Root defaultValue={1} min={0} max={10}>
  <NumberField.Group><NumberField.Decrement /><NumberField.Input aria-label="Quantity" /><NumberField.Increment /></NumberField.Group>
</NumberField.Root>

Use the exported component in the composition shown above. Keep labels, data, and callbacks in the consuming application.

Structure

Examples

Variants

Ghost

Remove the outer border when the surrounding surface already groups the control. The accent border marks the focused field.

Amount

Controls at the end

Put the value first and both step buttons after it. The value aligns to the start.

Amount

Optional value

Start empty when the quantity is optional. The first increase selects the minimum.

Optional seats

Invalid range

Keep the typed value visible and show the allowed range so it can be corrected.

Team seats

Use a value from 1 to 8.

Disabled

Show a value that cannot be changed in this step.

Team seats

Read-only

Expose a value for review while keeping direct entry and step actions unavailable.

Team seats

Stepped boundaries

Use a step of two and keep both controls bounded at zero and ten.

Retry limit

API reference

number-field properties
Prop	Type	Description
`className`	`string \| ((state: BaseUI.NumberFieldRootState) => string \| undefined) \| undefined`	CSS class applied to the element, or a function that returns a class based on the component's state.
`defaultValue`	`number \| undefined`	The uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the `value` prop instead.
`style`	`React.CSSProperties \| ((state: BaseUI.NumberFieldRootState) => React.CSSProperties \| undefined) \| undefined`	Style applied to the element, or a function that returns a style object based on the component's state.
`form`	`string \| undefined`	Identifies the form that owns the hidden input. Useful when the number field is rendered outside the form.
`disabled`	`boolean \| undefined`	Whether the component should ignore user interaction.
`name`	`string \| undefined`	Identifies the field when a form is submitted.
`value`	`number \| null \| undefined`	The raw numeric value of the field.
`id`	`string \| undefined`	The id of the input element.
`render`	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| BaseUI.ComponentRenderFn<BaseUI.HTMLProps, BaseUI.NumberFieldRootState> \| undefined`	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.
`step`	`number \| "any" \| undefined`	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. Specify `step="any"` to always disable step validation; interactive stepping then uses a base amount of `1`, while the alt and shift keys still step by `smallStep` and `largeStep`.
`onValueChange`	`((value: number \| null, eventDetails: BaseNumberField.Root.ChangeEventDetails) => void) \| undefined`	Callback fired when the number value changes. The `eventDetails.reason` indicates what triggered the change: - `'input-change'` for parseable typing or programmatic text updates - `'input-clear'` when the field becomes empty - `'input-blur'` when formatting (and clamping, if enabled) occurs on blur - `'input-paste'` for paste interactions - `'keyboard'` for arrow-key/Home/End stepping (typing digits uses `'input-change'`/`'input-clear'`) - `'increment-press'` / `'decrement-press'` for button presses on the increment and decrement controls - `'wheel'` for wheel-based scrubbing - `'scrub'` for scrub area drags
`max`	`number \| undefined`	The maximum value of the input element.
`min`	`number \| undefined`	The minimum value of the input element.
`readOnly`	`boolean \| undefined`	Whether the user should be unable to change the field value.
`required`	`boolean \| undefined`	Whether the user must enter a value before submitting a form.
`inputRef`	`React.Ref<HTMLInputElement> \| undefined`	A ref to access the hidden input element.
`locale`	`Intl.LocalesArgument`	The locale of the input element. Defaults to the user's runtime locale.
`format`	`Intl.NumberFormatOptions \| undefined`	Options to format the input value.
`allowOutOfRange`	`boolean \| undefined`	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.
`smallStep`	`number \| undefined`	The small step value of the input element when incrementing while the alt key is held. Snaps to multiples of this value when `snapOnStep` is enabled.
`largeStep`	`number \| undefined`	The large step value of the input element when incrementing while the shift key is held. Snaps to multiples of this value when `snapOnStep` is enabled.
`allowWheelScrub`	`boolean \| undefined`	Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input.
`snapOnStep`	`boolean \| undefined`	Whether the value should snap to the nearest step when incrementing or decrementing.
`onValueCommitted`	`((value: number \| null, eventDetails: BaseNumberField.Root.CommitEventDetails) => void) \| undefined`	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 runs simultaneously with `onValueChange` when interacting with the keyboard or the mouse wheel. Warning: This is a generic event not a change event.

This component wraps Base UI number-field for its behavior.