Number Field

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import NumberField, NumberFieldLimitEdge, NumberFieldSize from @prepared911/ui/number-field.

Prop	Type	Default	Notes
`value`, `defaultValue`	`number \| null`	uncontrolled, `null`	`null` is empty.
`onValueChange`	`(value, details) => void`		Reasons: `input-change`, `keyboard-step`, `item-press`, `press-hold`, `drag`, `drag-cancel`, `form-reset`. Cancelable except `drag-cancel` and `form-reset`.
`min`, `max`	`number \| string`	unbounded	Clamp every path. A finite `min` starts the step grid; a negative `min` allows a minus in the draft.
`step`	`number \| string`	`1`	Grid for snapping. `"any"` removes snapping and steps by `1`.
`largeStep`	`number`	ten steps	Shift+Arrow, PageUp, PageDown.
`label`, `description`, `error`, `invalid`			Setting `label`, `description` or `error` wraps the control in the field stack. `error` shows while `invalid` or `aria-invalid` is true.
`decrementLabel`, `incrementLabel`	`LocalizedMessage`		Accessible names of the step buttons; a button is not rendered without its name.
`prefix`, `suffix`	`LocalizedMessage \| (value) => LocalizedMessage`		Rendered through the rolling digits.
`locale`	`string`	runtime locale	Digits, draft symbols and speech, as in Text value mode. Pass it explicitly when a server-rendered page must match the client.
`formatOptions`	`Intl.NumberFormatOptions`	derived from `step` and `min`
`roll`	`boolean`	`true`	`false` shows the value as static formatted text: no wheel, no blur and no column or affix enter or exit motion. The caret, draft, semantics and limits are unchanged.
`scrub`	`boolean`	`false`	Drag the label sideways to change the value. Needs `label`.
`limitHint`	`boolean`	`true`	Shows the note beside the label.
`limitNote`	`(edge, formattedLimit) => LocalizedMessage`	formatted limit
`valueAnnouncement`	`(formattedValue, edge) => LocalizedMessage`	formatted value	Polite live region after a button step or a limit.
`size`	`InputSize`	`Large`

Every other native input attribute (name, form, required, disabled, readOnly, id, aria-*) goes to the input. name submits the canonical number through a hidden input.

Input purpose

autoComplete and name are typed with the shared InputPurposeProps. The visible input renders inputMode="numeric" ("decimal" when the step or bounds allow fractions), spellCheck={false} and autoComplete="off"; an autoComplete token you pass, such as bday-year, replaces off. name is submitted through a hidden input that carries the canonical number, not the formatted text.

Props

Name	Type	Default	Description
`autoComplete`	`HTMLInputAutoCompleteAttribute`	—	Autofill purpose token. Set it on every field that collects information about the user: `name`, `email`, `tel`, `street-address`, `postal-code`, `username`, `current-password`, `new-password`, `one-time-code`, or a section and `shipping` or `billing` prefix before one. Input turns spellcheck off for identifier purposes. Do not pass `off` to a field that collects personal data; no design-system control defaults to it except NumberField, which a token replaces.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`decrementLabel`	`LocalizedMessage`	—	Accessible name of the decrement button. The button is not rendered without it.
`defaultValue`	`number \| null`	—	Initial value when uncontrolled. Drives {@link useControlled } and form `reset` restoration.
`description`	`LocalizedMessage`	—	Supporting copy below the control, linked with `aria-describedby`.
`error`	`LocalizedMessage`	—	Error copy below the control while {@link invalid} is true, linked with `aria-errormessage`.
`formatOptions`	`NumberFormatOptions`	—	`Intl.NumberFormat` options for the displayed value. They win over the fraction digits derived from `step` and `min`.
`incrementLabel`	`LocalizedMessage`	—	Accessible name of the increment button. The button is not rendered without it.
`invalid`	`boolean`	—	When true, the control paints the invalid edge and exposes `aria-invalid`. `aria-invalid` on its own does the same.
`label`	`LocalizedMessage`	—	Visible label above the control. Setting it (or `description` or `error`) wraps the control in a field stack that wires the label, description and error to the input. Without it, NumberField renders the control alone and the caller supplies a Label or `aria-label`; the limit note then has no label to sit beside.
`largeStep`	`number`	—	Distance of a large step (Shift+Arrow, PageUp, PageDown). Defaults to ten steps.
`limitHint`	`boolean`	`true`	Whether the note beside the label appears when a limit is met. The polite announcement is unaffected.
`limitNote`	`NumberFieldLimitNoteCopy`	—	Copy for the limit note. Defaults to the formatted limit alone.
`locale`	`string`	—	BCP 47 locale for the digits, the group and decimal symbols a draft accepts, and speech. Defaults to the runtime locale, as Text's value mode does, so a server-rendered app that must match the client passes it explicitly.
`max`	`string \| number`	—	Upper bound. Typed values, steps and scrubbing clamp to it. Unbounded when omitted.
`min`	`string \| number`	—	Lower bound. Typed values, steps and scrubbing clamp to it. Unbounded when omitted. The step grid starts here when it is finite, and a negative `min` lets the draft take a minus sign.
`name`	`string`	—	Form control name, submitted with the form. Browsers also read it as an autofill hint, so pass a meaningful one.
`onValueChange`	`((value: number \| null, details: ChangeDetails<NumberFieldValueChangeReason>) => void)`	—	Called for every value change, including controlled mode and form `reset`.
`placeholder`	`LocalizedMessage`	—	Placeholder copy when the field is empty.
`prefix`	`NumberFieldAffix`	—	Text before the value, inside the control.
`ref`	`Ref<HTMLInputElement>`	—	Ref to the rendered `input`.
`roll`	`boolean`	`true`	Roll the digits to each new value, and animate the affix characters as they change. `false` shows the value as static formatted text: no wheel, no blur and no column or affix enter or exit motion. The caret, the draft, the spinbutton semantics and the limits behave the same either way.
`scrub`	`boolean`	`false`	When true, dragging the label sideways changes the value one step every few pixels. Past a limit the value follows the pointer with rubber-band resistance and springs back on release. The label click after a drag is suppressed.
`size`	`InputSize`	—	Control scale. Defaults to {@link InputSize.Large}.
`step`	`string \| number`	—	Distance between values. Typed drafts snap to this grid on commit, and fraction digits default to its precision. Defaults to `1`. `"any"` removes snapping and steps by `1`.
`suffix`	`NumberFieldAffix`	—	Text after the value, inside the control.
`value`	`number \| null`	—	Controlled numeric value. `undefined` on the first render is uncontrolled; `null` is a controlled empty value.
`valueAnnouncement`	`NumberFieldValueAnnouncementCopy`	—	Copy for the live announcement after a button step or a limit. Defaults to the formatted value alone.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Number Field / Usage

Number Field / Accessibility

On this page

Input purpose

Props

Storybook

Number Field

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Import NumberField, NumberFieldLimitEdge, NumberFieldSize from @prepared911/ui/number-field.

Prop	Type	Default	Notes
`value`, `defaultValue`	`number \| null`	uncontrolled, `null`	`null` is empty.
`onValueChange`	`(value, details) => void`		Reasons: `input-change`, `keyboard-step`, `item-press`, `press-hold`, `drag`, `drag-cancel`, `form-reset`. Cancelable except `drag-cancel` and `form-reset`.
`min`, `max`	`number \| string`	unbounded	Clamp every path. A finite `min` starts the step grid; a negative `min` allows a minus in the draft.
`step`	`number \| string`	`1`	Grid for snapping. `"any"` removes snapping and steps by `1`.
`largeStep`	`number`	ten steps	Shift+Arrow, PageUp, PageDown.
`label`, `description`, `error`, `invalid`			Setting `label`, `description` or `error` wraps the control in the field stack. `error` shows while `invalid` or `aria-invalid` is true.
`decrementLabel`, `incrementLabel`	`LocalizedMessage`		Accessible names of the step buttons; a button is not rendered without its name.
`prefix`, `suffix`	`LocalizedMessage \| (value) => LocalizedMessage`		Rendered through the rolling digits.
`locale`	`string`	runtime locale	Digits, draft symbols and speech, as in Text value mode. Pass it explicitly when a server-rendered page must match the client.
`formatOptions`	`Intl.NumberFormatOptions`	derived from `step` and `min`
`roll`	`boolean`	`true`	`false` shows the value as static formatted text: no wheel, no blur and no column or affix enter or exit motion. The caret, draft, semantics and limits are unchanged.
`scrub`	`boolean`	`false`	Drag the label sideways to change the value. Needs `label`.
`limitHint`	`boolean`	`true`	Shows the note beside the label.
`limitNote`	`(edge, formattedLimit) => LocalizedMessage`	formatted limit
`valueAnnouncement`	`(formattedValue, edge) => LocalizedMessage`	formatted value	Polite live region after a button step or a limit.
`size`	`InputSize`	`Large`

Every other native input attribute (name, form, required, disabled, readOnly, id, aria-*) goes to the input. name submits the canonical number through a hidden input.

Input purpose

Props

Name	Type	Default	Description
`autoComplete`	`HTMLInputAutoCompleteAttribute`	—	Autofill purpose token. Set it on every field that collects information about the user: `name`, `email`, `tel`, `street-address`, `postal-code`, `username`, `current-password`, `new-password`, `one-time-code`, or a section and `shipping` or `billing` prefix before one. Input turns spellcheck off for identifier purposes. Do not pass `off` to a field that collects personal data; no design-system control defaults to it except NumberField, which a token replaces.
`className`	`string`	—	Classes appended after the generated classes. Put overrides in `@layer chroma.overrides`.
`decrementLabel`	`LocalizedMessage`	—	Accessible name of the decrement button. The button is not rendered without it.
`defaultValue`	`number \| null`	—	Initial value when uncontrolled. Drives {@link useControlled } and form `reset` restoration.
`description`	`LocalizedMessage`	—	Supporting copy below the control, linked with `aria-describedby`.
`error`	`LocalizedMessage`	—	Error copy below the control while {@link invalid} is true, linked with `aria-errormessage`.
`formatOptions`	`NumberFormatOptions`	—	`Intl.NumberFormat` options for the displayed value. They win over the fraction digits derived from `step` and `min`.
`incrementLabel`	`LocalizedMessage`	—	Accessible name of the increment button. The button is not rendered without it.
`invalid`	`boolean`	—	When true, the control paints the invalid edge and exposes `aria-invalid`. `aria-invalid` on its own does the same.
`label`	`LocalizedMessage`	—	Visible label above the control. Setting it (or `description` or `error`) wraps the control in a field stack that wires the label, description and error to the input. Without it, NumberField renders the control alone and the caller supplies a Label or `aria-label`; the limit note then has no label to sit beside.
`largeStep`	`number`	—	Distance of a large step (Shift+Arrow, PageUp, PageDown). Defaults to ten steps.
`limitHint`	`boolean`	`true`	Whether the note beside the label appears when a limit is met. The polite announcement is unaffected.
`limitNote`	`NumberFieldLimitNoteCopy`	—	Copy for the limit note. Defaults to the formatted limit alone.
`locale`	`string`	—	BCP 47 locale for the digits, the group and decimal symbols a draft accepts, and speech. Defaults to the runtime locale, as Text's value mode does, so a server-rendered app that must match the client passes it explicitly.
`max`	`string \| number`	—	Upper bound. Typed values, steps and scrubbing clamp to it. Unbounded when omitted.
`min`	`string \| number`	—	Lower bound. Typed values, steps and scrubbing clamp to it. Unbounded when omitted. The step grid starts here when it is finite, and a negative `min` lets the draft take a minus sign.
`name`	`string`	—	Form control name, submitted with the form. Browsers also read it as an autofill hint, so pass a meaningful one.
`onValueChange`	`((value: number \| null, details: ChangeDetails<NumberFieldValueChangeReason>) => void)`	—	Called for every value change, including controlled mode and form `reset`.
`placeholder`	`LocalizedMessage`	—	Placeholder copy when the field is empty.
`prefix`	`NumberFieldAffix`	—	Text before the value, inside the control.
`ref`	`Ref<HTMLInputElement>`	—	Ref to the rendered `input`.
`roll`	`boolean`	`true`	Roll the digits to each new value, and animate the affix characters as they change. `false` shows the value as static formatted text: no wheel, no blur and no column or affix enter or exit motion. The caret, the draft, the spinbutton semantics and the limits behave the same either way.
`scrub`	`boolean`	`false`	When true, dragging the label sideways changes the value one step every few pixels. Past a limit the value follows the pointer with rubber-band resistance and springs back on release. The label click after a drag is suppressed.
`size`	`InputSize`	—	Control scale. Defaults to {@link InputSize.Large}.
`step`	`string \| number`	—	Distance between values. Typed drafts snap to this grid on commit, and fraction digits default to its precision. Defaults to `1`. `"any"` removes snapping and steps by `1`.
`suffix`	`NumberFieldAffix`	—	Text after the value, inside the control.
`value`	`number \| null`	—	Controlled numeric value. `undefined` on the first render is uncontrolled; `null` is a controlled empty value.
`valueAnnouncement`	`NumberFieldValueAnnouncementCopy`	—	Copy for the live announcement after a button step or a limit. Defaults to the formatted value alone.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Number Field / Usage

Number Field / Accessibility

On this page

Input purpose

Props

Storybook