NumberField

NumberField is a compound component for numeric entry with optional stepper buttons, bounds, masking, and wheel or keyboard stepping.

Storybook Source Figma

Root Props

Prop	Type	Default
`value`	`number`	—
Controlled value. `NaN` means the field is empty.
`defaultValue`	`number`	`NaN`
Initial value for uncontrolled usage. Defaults to `NaN`, an empty field.
`onChangeValue`	`(value: number) => void`	—
Called with the number when it changes, `NaN` when the field is emptied.
`step`	`number`	`1`
Amount to increment or decrement the value by when using arrow keys or spinner controls.
`min`	`number`	`Number.MIN_SAFE_INTEGER`
Minimum allowed value for the input. Enforced both via HTML attributes and internal logic.
`max`	`number`	`Number.MAX_SAFE_INTEGER`
Maximum allowed value for the input.
`ref`	`Ref<HTMLDivElement>`	—
Ref forwarded to the element.
`precision`	`number`	`0`
Number of decimal places to round the input value to. Useful for financial or scientific precision.
`changeOnWheel`	`boolean`	`true`
Enables changing the value with the mouse wheel when focused.
`allowEmpty`	`boolean`	`true`
Allows the field to be empty (null/undefined) instead of defaulting to 0. Useful for optional numeric inputs.
`maximumFractionDigits`	`number`	`2`
Maximum number of digits allowed after the decimal point. This property controls numeric precision when the value is entered or adjusted via increment/decrement actions. It is commonly used for currency values, measurements, or ratings where fractional precision must be constrained. Example: `maximumFractionDigits={0}` → integers only; `maximumFractionDigits={2}` → up to two decimal places
`disabled`	`boolean`	—
Disables the entire NumberField.
`size`	`TextFieldSize`	`'md'`
Visual size of the text field. Affects padding, font size, and overall height. 'sm': Compact input; 'md': Default; 'lg': Spacious layout
`error`	`boolean`	—
Shows the input in an error state.

Also accepts all <div> attributes.

Child Parts

NumberFieldInput: numeric input bound to context.
NumberFieldIncrementButton: increment control.
NumberFieldDecrementButton: decrement control.

`NumberFieldDecrementButton`

Prop	Type	Default
`size`	`IconButtonSize`	—
Size of the button container. Controls padding and overall clickable area.
`asChild`	`boolean`	—
When true, renders the button as a child component using `Slot` (e.g., from Radix UI). Enables polymorphic rendering — useful for making the button act as a link or custom tag.
`variant`	`ButtonBaseVariant`	—
Defines the visual style of the button, affecting color schemes and emphasis.
`appearance`	`ButtonBaseAppearance`	—
Adjusts the button's structural appearance (background, border, etc.).
`disabled`	`boolean`	—
Disables the button when true. Prevents user interaction and applies a visually disabled state. Not applied with `asChild`: the child element owns its disabled state, for example, `aria-disabled` or a link without `href`.
`className`	`string`	—
Optional custom CSS class for the button element. Useful for design system overrides or scoped styles.
`children`	`ReactNode`	—
Content of the button — text, icon, or any React node.
`ref`	`Ref<HTMLButtonElement>`	—
Ref forwarded to the native `<button>` element. Allows direct DOM access for focus management or measuring.

Also accepts all <button> attributes.

`NumberFieldIncrementButton`

Prop	Type	Default
`size`	`IconButtonSize`	—
Size of the button container. Controls padding and overall clickable area.
`asChild`	`boolean`	—
When true, renders the button as a child component using `Slot` (e.g., from Radix UI). Enables polymorphic rendering — useful for making the button act as a link or custom tag.
`variant`	`ButtonBaseVariant`	—
Defines the visual style of the button, affecting color schemes and emphasis.
`appearance`	`ButtonBaseAppearance`	—
Adjusts the button's structural appearance (background, border, etc.).
`disabled`	`boolean`	—
Disables the button when true. Prevents user interaction and applies a visually disabled state. Not applied with `asChild`: the child element owns its disabled state, for example, `aria-disabled` or a link without `href`.
`className`	`string`	—
Optional custom CSS class for the button element. Useful for design system overrides or scoped styles.
`children`	`ReactNode`	—
Content of the button — text, icon, or any React node.
`ref`	`Ref<HTMLButtonElement>`	—
Ref forwarded to the native `<button>` element. Allows direct DOM access for focus management or measuring.

Also accepts all <button> attributes.

`NumberFieldInput`

Prop	Type	Default
`ref`	`Ref<HTMLInputElement>`	—
Ref forwarded to the underlying native `<input>` element.

Also accepts all <input> attributes.

Types

NumberFieldProps
NumberFieldInputProps
NumberFieldIncrementProps
NumberFieldDecrementProps
NumberFieldSize

State Model

The root tracks whether the current value is at min or max.
Arrow keys and optional wheel events step the value through root logic. Like <input type="number">, the wheel steps only the focused field; without focus it scrolls the page.
A step keeps the decimals of the value and of step (0.7 + 0.1 gives 0.8).
A root onKeyDown runs after the built-in arrow handling and does not replace it.
The root takes value, defaultValue and onChangeValue as a number, NaN for an empty field; NumberFieldInput shows the formatted text and still fires its own onChange and onInput. A form reset restores defaultValue unless the field is controlled.