number-field

Accessible spinbutton input with stepper buttons, clamping, and locale-aware formatting.

A headless number field following the WAI-ARIA spinbutton pattern. Shows a locale-formatted value when unfocused; switches to the raw numeric string on focus so the user can edit digits directly. Arrow / Page / Home / End keys step the value; increment and decrement buttons are disabled at the bounds.

Installation

pnpm add @fluixi/number-field

Usage

import {
  NumberField,
  NumberFieldLabel,
  NumberFieldInput,
  NumberFieldIncrement,
  NumberFieldDecrement,
} from '@fluixi/number-field';

<NumberField defaultValue={5} min={0} max={100} step={1} onChange={console.log}>
  <NumberFieldLabel>Quantity</NumberFieldLabel>
  <NumberFieldDecrement>−</NumberFieldDecrement>
  <NumberFieldInput />
  <NumberFieldIncrement>+</NumberFieldIncrement>
</NumberField>

Props (`NumberField`)

Prop	Type	Default	Description
`value`	`number`	—	Controlled value.
`defaultValue`	`number`	—	Initial uncontrolled value.
`onChange`	`(v: number) => void`	—	Called after each committed change.
`min`	`number`	—	Lower bound; clamps and disables decrement at boundary.
`max`	`number`	—	Upper bound; clamps and disables increment at boundary.
`step`	`number`	`1`	Arrow key / button step size.
`largeStep`	`number`	`step × 10`	Page Up/Down step size.
`locale`	`string`	`'en-US'`	`Intl.NumberFormat` locale for display.
`formatOptions`	`Intl.NumberFormatOptions`	`{}`	Additional format options (e.g. `{ style: 'currency', currency: 'USD' }`).
`disabled`	`boolean`	`false`	Disables the input and both buttons.
`required`	`boolean`	`false`	Sets `aria-required` on the input.
`name`	`string`	—	Renders a hidden `<input>` for native form submission.

Parts

Part	Description
`NumberField`	Root `<div>`. Provides context; owns the value signal.
`NumberFieldLabel`	`<label>` wired to the input via generated IDs.
`NumberFieldInput`	`<input role="spinbutton">`. Handles all keyboard events and focus/blur formatting.
`NumberFieldIncrement`	`<button>` that calls `increment()`; disabled at `max`.
`NumberFieldDecrement`	`<button>` that calls `decrement()`; disabled at `min`.

Keyboard

Key	Action
`ArrowUp`	Increment by `step`
`ArrowDown`	Decrement by `step`
`PageUp`	Increment by `largeStep`
`PageDown`	Decrement by `largeStep`
`Home`	Set to `min`
`End`	Set to `max`

Part of the Fluixi UI component library. Made with ☕ by the Fluixi team.