Components / Controls

NumberField

A field for numbers. People type in their own format or step the value with the keyboard or the − and + buttons; your code gets a number.

Source Edit this page

Spin button with its value

When to use

Quantities, amounts, limits, measurements: values people may want to nudge up and down.

Use something else when:

the value is picked on a scale and the exact number matters less: Slider
it is digits that are not a quantity (a phone number, a code, a card number): TextField with inputMode="numeric"

Usage

tsx

import { NumberField } from "@arshad-shah/cynosure";

<NumberField label="Seats" value={seats} onChange={setSeats} min={1} max={50} />

onChange fires when a value is committed: on each step, on Enter, and when leaving the field after typing. It receives a number, or null when the field is emptied.

Formats and locales

Numbers are read and written with Intl.NumberFormat for locale (default: the browser's) and formatOptions: currencies, percents, units, fixed digits. People can type group separators, the local decimal mark and a typographic minus. Percents are typed as people say them: 20 means 20%, stored as 0.2.

Forms

With name, the form receives the plain number ("1234.5"), whatever the text shows. Reset restores defaultValue; disabled fields are not submitted; required makes an empty field invalid.

Forms get the plain number

Props

Every prop of NumberField
Prop	What it does	Type	Default
`label`Required	Visible label; it names the field.	`ReactNode`
`labelHidden`	Visually hide the label (it still names the field). Prefer visible labels.	`boolean`
`description`	Help text shown below the field.	`ReactNode`
`error`	Error message shown below the field; it marks the field invalid.	`ReactNode`
`value`	`null` is empty.	`number \| null`
`defaultValue`	Starting value when uncontrolled; `null` is empty.	`number \| null`
`onChange`	Called with the new value when it is committed: a step, Enter, or leaving the field.	`((value: number \| null) => void)`
`min`	Smallest value. Typed and stepped values are kept at or above it, and Home jumps to it.	`number`
`max`	Largest value. Typed and stepped values are kept at or below it, and End jumps to it.	`number`
`step`	Arrow keys and steppers move by this; values they produce snap to it. Default 1.	`number`	`1`
`largeStep`	Page Up and Page Down move by this. Default: 10 steps.	`number`	`10 steps`
`locale`	Locale for reading and writing numbers. Default: the browser's.	`string`	`the browser's`
`formatOptions`	How the value is written: currency, percent, units, digits… (`Intl.NumberFormat` options).	`Intl.NumberFormatOptions`
`hideSteppers`	Hide the − and + buttons (the keyboard still steps).	`boolean`
`name`	Name the plain number is submitted under in a form.	`string`
`form`	Id of the form it belongs to, when it is not inside that form.	`string`
`required`	Marks the field as required for form validation.	`boolean`
`disabled`	Turns off the field and its stepper buttons.	`boolean`
`readOnly`	The value can be read but not changed.	`boolean`
`placeholder`	Hint shown while the field is empty.	`string`
`size`	Size of the field. Default "md".	`Size`	`"md"`
`variant`	`outline` or `soft` (tinted, borderless until focus). Default "outline".	`"soft" \| "outline"`	`"outline"`
`labels`	Replace the built-in English text: the stepper button names.	`Partial<NumberFieldLabels>`
`scrub`	Drag the label sideways to change the value, as design tools do: one `step` every few pixels, Shift for ten. Escape mid-drag puts it back. The keys and the steppers still work as before.	`boolean`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only.	`CSSProperties`
`layout`	`stack` puts the label above the control and the description and error below it. `split` puts the label and description at the start and the control at the end of one row (a settings row); when the field is too narrow for both, the control moves under the text. Default "stack".	`"stack" \| "split"`	`"stack"`
`width`	Width of the control, so the controls of a column of fields line up: "sm", "md" and "lg" are the `--cy-field-control-width-*` tokens (never wider than the field), "full" is the whole field. Default: the control's own width (the whole field in the stacked layout for TextField and the other fields).	`FieldWidth`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Role: role="spinbutton", named by its label, with aria-valuenow, aria-valuemin, aria-valuemax and the formatted value as aria-valuetext.
Keyboard:

Behaviour and accessibility, table 1
Key	Action
Arrow Up / Arrow Down	One `step` up or down
Page Up / Page Down	`largeStep` (10 steps) up or down
Home / End	To `min` / `max` (when set)
Enter	Commit the typed text

Stepping: stepped values snap to step, counted from min, and never pick up floating-point noise (0.1 + 0.2 is 0.3). The steppers are disabled at the limits.
Typing: unreadable text goes back to the last value; values outside min and max are clamped.
Steppers: not tab stops (the field is one stop, as in the APG pattern); their hit areas are at least 24px, 44px on touch screens; pressing one keeps focus in the field.
Mobile keyboards: inputmode is numeric for whole non-negative numbers and decimal otherwise.
Labels: "Decrease" and "Increase" are in labels.

Theming

NumberField uses TextField's tokens (--cy-text-field-*); digits are tabular so columns of numbers line up.

TextField · Slider · Field

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Formats and localesLink to "Formats and locales"

FormsLink to "Forms"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"

RelatedLink to "Related"