Number field
A quantity field that formats for the page’s locale, clamps to its bounds, and steps from the keyboard or its own spin buttons.
Installation
npx shadcn@latest add @flyingsalmon/number-fieldUsage
import { useState } from 'react'
import { NumberField } from '@/components/ui/number-field'
export function NumberFieldUsage() {
const [travellers, setTravellers] = useState<number | null>(2)
return (
<NumberField
label="Travellers"
value={travellers}
onValueChange={setTravellers}
min={1}
/>
)
}Examples
Budget with a prefix
prefix puts a symbol before the value and step sizes one press of a spin button. The prefix is plain text, so it reads the way your product writes money, and the value still groups for the locale.
Duration with a unit
Home jumps to min and End to max, and each spin button dims as its end arrives.
Sizes
Two sizes match Input, so a number field and a text field line up in a row.
Description
Helper text shows the other view of the amount: the group total for a per-person budget. Step below $100 and the error grows in beneath it.
$7,200 for 4 travellers
Error
The border, the dividers, and the label turn destructive together.
Book for at least one traveller
Loading
Change the budget. A spinner replaces the spin buttons in exactly their width while the trips are counted, and the field stays typeable.
Disabled
The spin buttons stay in place and dim with the field, so the control never changes shape as it locks.
Read-only
The value stays readable and copyable, and the field still posts with its form.
Guidelines
When to use
- For a quantity the traveller adjusts: travellers, nights, a budget.
- When the value is arithmetic input and the field must report a number, with bounds you can enforce.
When not to use
Do and don’t
- DoGive every quantity its unit: "$" before a budget, "people" after a group size.The number reads as a phrase, so nobody wonders whether 4 means nights or travellers.
- DoBound the field by the real limits of what it counts, such as 2 to 30 people.The field and its spin buttons refuse the impossible as the traveller enters it, so no error has to arrive afterwards.
- Don’tStretch the field across the form column.A quantity is a few digits. A field sized to its number reads as a count; a wide one looks like it wants a sentence.
- DoOffer a slider beside the exact entry when "roughly" is a fair answer, and let the traveller swap between them.A traveller who knows the figure types it, and one who does not can still answer without guessing a precise number.
- Don’tLock the field while a background check runs.A spinner takes the place of the spin buttons and the field stays typeable. Only the submit button locks a flow.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves focus into the field and then out. The spin buttons are outside the tab order, because the arrow keys already do their job. |
| ArrowUpArrowDown | Steps the value by step. |
| PageUpPageDownShift+ArrowUpShift+ArrowDown | Steps the value by largeStep, ten times step unless you set it. |
| HomeEnd | Jumps to min or max. Does nothing when that bound is unset. |
| Enter | Commits the typed text and lets the form submit. |
| Escape | Does nothing here, so it still closes an enclosing dialog. |
The mouse wheel never steps the value, so scrolling through a form cannot change an answer. The text input is the spinbutton. Its value text includes the prefix and the unit, so a screen reader hears “$1,500” rather than “1500”, and an empty field omits its value attributes instead of announcing a number it does not have. The spin buttons are named Decrease and Increase. required marks the label and sets aria-required; the validation itself stays with your app. The states every field shares are described on Fields.
API
NumberField
Also takes every <input> attribute except type, size, and the value props it redefines. className styles the wrapper, so a width set there sizes the whole field.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | – | The visible label. Renders above the field and is wired to it. |
| value | number | null | – | The controlled value. null is an empty field, never NaN or 0, so a blank and a zero stay apart. |
| defaultValue | number | null | – | The initial value of an uncontrolled field. |
| onValueChange | (value: number | null) => void | – | Reports the parsed number while typing, in range or not, and null when the field is empty. It is always a plain number, so read it rather than the typed text, which carries the locale’s group separator. Blur and Enter clamp into [min, max] and reformat. |
| min | number | – | The floor. Set it on every count that cannot go negative: it bounds the clamp, gives Home somewhere to jump, disables Decrease at the floor, and picks the numeric mobile keyboard when it is zero or above. |
| max | number | – | The ceiling. |
| step | number | 1 | One arrow key or spin button press. A fractional step picks the decimal keyboard. |
| largeStep | number | step * 10 | One Page Up, Page Down, or shifted arrow press. |
| prefix | string | – | Plain text before the value, such as "$". |
| unit | string | – | Plain text after the value, such as "days". |
| locale | string | – | The locale for grouping and the decimal mark. Defaults to the page’s language. |
| size | NumberFieldSize | NumberFieldSize.Default | Default and Small match the field heights of the same names. |
| description | string | – | Helper text under the field. |
| error | string | – | The failure message. Turns the border, the ring, and the label destructive. Text the parser cannot read reverts to the last value without raising one. |
| loading | boolean | false | Replaces the spin buttons with a spinner. The field stays typeable. Set it, not disabled, while a background check runs. |
| disabled | boolean | false | Dims the field, takes no pointer events, and posts nothing. |
| readOnly | boolean | false | Keeps the value readable and focusable. The field still posts. |