Number Field
Take seats, prices, and percentages as numbers, formatted for the reader's locale and kept within your limits.
Installation
You can add the number field using our CLI or manually:
Dark mode ready - this component follows BoardUI semantic tokens automatically. Set up theme switching.
The CLI copies the component source (with its internal dependencies) into your project and installs any required npm packages.
npx boardui@latest add number-fieldUsing a shared UI package or custom import aliases? Configure your installation paths before running the CLI. Copy-paste examples use the default imports.
Formatting
formatOptions takes the options of Intl.NumberFormat: currency, percent, and unit styles, and how many decimals to show. The value stays a plain number, so a percent field holds 0.25 for 25%.
<NumberField label="Package weight" defaultValue={2.4} step={0.1} formatOptions={{ style: "unit", unit: "kilogram" }} /><NumberField label="Storage" defaultValue={250} step={50} formatOptions={{ style: "unit", unit: "gigabyte" }} /><NumberField label="Conversion rate" defaultValue={0.034} step={0.001} formatOptions={{ style: "percent", minimumFractionDigits: 1 }} /><NumberField label="Budget" defaultValue={1500} step={100} formatOptions={{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }} />Limits and steps
minValue and maxValue clamp what people type when the field loses focus, and each stepper switches off at its limit. step sets how far a stepper or an arrow key moves the value, and typed values snap to it.
<NumberField label="Quantity" defaultValue={10} minValue={1} maxValue={10} hint="Up to 10 per order." /><NumberField label="Rating" defaultValue={4.5} minValue={0} maxValue={5} step={0.5} /><NumberField label="Retries" size="small" defaultValue={3} minValue={0} maxValue={9} /><NumberField label="Seats" size="small" defaultValue={8} isDisabled hint="Managed by your admin." />Right-to-left
Inside DirectionProvider, the steppers move to the left and numbers are written and read in the locale's own digits.
import { DirectionProvider } from "@/components/foundations/direction/direction";
<DirectionProvider locale="ar"> <NumberField label="عدد المقاعد" defaultValue={5} minValue={1} maxValue={50} /> <NumberField label="سعر المقعد" defaultValue={12} formatOptions={{ style: "currency", currency: "USD" }} /></DirectionProvider>Keyboard and accessibility
Up and Down step the value, and Home and End jump to the limits when they are set. Typing accepts only characters that can make a number in the locale. The field is announced as a spin button with its formatted value, and the steppers stay out of the tab order.
While the field has focus, the scroll wheel steps the value too. Set isWheelDisabled where the field sits in a scrolling page and that would surprise people.