Type an exact number, or nudge it with − / + steppers.
Default
Type a number or use the − / + steppers; arrow keys step and Home/End jump to the limits.
Between 1 and 50 people on the workspace.
Installation
Copies the component into src/design-system/ as your own source, with only the files it needs.
npx avesk-ui@latest add number-fieldBrings the 5 files it builds on (field.tsx, icon.tsx, select-menu.tsx, floating.tsx, glyph.tsx). The first time, it also adds the tokens and the cn() helper, imports the tokens in globals.css and installs clsx and tailwind-merge. Files already in your project are kept unless you add --force.
Import
Lives in src/design-system/components/number-field.tsx.
import { NumberField } from "@/design-system/components/number-field";Usage
<NumberField label="Seats" value={seats} onValueChange={setSeats} minValue={1} maxValue={50} step={1} hint="Between 1 and 50 people." />Examples
Units, percent and currency
formatOptions shows the value as kg, GB, a percent or euros; the field still holds a plain number.
Share of the fee paid up front.
Limits, steps and sizes
Steppers disable at the limit, typed values snap to the step, plus the small size and the disabled state.
Up to 10 per order.
Set by the workspace owner.
Controlled
Hold the values in state with value and onValueChange when other UI depends on them.
Monthly total: $116.00
When to use
Use it when
- An exact number matters: seats, quantity, hours, a price, a percentage
- Small changes around a known value, where − / + saves typing
Don’t use it when
- An approximate value in a range is enough → Slider
- The "number" is an ID, phone or card number (never stepped or summed) → Field and inputs (Input)
Rules
- Set minValue / maxValue whenever the domain has limits; the steppers disable there
- Show units with formatOptions (unit, percent, currency), not in the label or a prefix
- Store plain numbers: a percent field holds 0.25 for 25%, a currency field holds 49.5
- Pass step when typed values must land on a grid (whole seats, half stars)
Properties
NumberField
| Prop | Type | Default |
|---|---|---|
label | string | – |
hint | string | – |
error | string | – |
required | boolean | – |
value | number | null | – |
defaultValue | number | null | null |
onValueChange | (value: number | null) => void | – |
minValue | number | – |
maxValue | number | – |
step | number | – |
formatOptions | Intl.NumberFormatOptions | – |
locale | string | "en-US" |
disabled | boolean | – |
size | "sm" | "md" | "md" |
wheelDisabled | boolean | – |
placeholder | string | – |
name | string | – |
id | string | – |
className | string | – |
aria-label | string | – |
* required
Accessibility
- Text input with role="spinbutton" plus aria-valuenow / min / max; aria-valuetext carries the formatted value ("12 kg", "25%")
- Up/Down arrows step, Home/End jump to min/max; the − / + buttons are out of the tab order (tabIndex -1) and named "Decrease" / "Increase"
- Pass label or aria-label; hint and error are linked with aria-describedby and error sets aria-invalid
- The scroll wheel only steps while the field has focus, so scrolling the page never changes a value