The NumberField component is a flexible and accessible input field for numerical values, built with React and integrated with shadcn/ui. It offers customizable increment and decrement buttons, supports various layouts, and includes built-in error handling and validation. This component is designed to be highly adaptable, making it suitable for a wide range of applications where numerical input is required.
This component set includes the following sub-components:
<NumberField name="..." value="..." onChange={...} className="...">
<NumberFieldLabel>{/* label */}</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>{/* increment icon */}</NumberFieldIncrement>
<NumberFieldInput className="..." />
<NumberFieldDecrement>{/* decrement icon */}</NumberFieldDecrement>
</NumberFieldGroup>
<NumberFieldError />
</NumberField>
Key features include:
- Customizable button placement (inside or outside the input)
- Flexible label positioning
- Internationalization support
- Accessibility features using React Aria
- Integration with shadcn/ui components and styling
- Compound component structure for easy customization
npx shadcn@latest add "https://v0.dev/chat/b/jkZcwYy"
-
Make sure that the relevant dependencies of
react-aria
andreact-stately
have been installed. -
Copy the code in
packages/number-field/src/number-field.tsx
to your project. -
Then import the required modules in your component file.
<NumberField>
<NumberFieldLabel>Amount</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement />
</NumberFieldGroup>
</NumberField>
<form
action={create}
// onSubmit={handleSubmit}
className='flex gap-4 flex-col p-8'
>
<input
className='border border-gray-200'
type='text'
name='username'
placeholder='username'
/>
<input
className='border border-gray-200'
type='password'
name='password'
placeholder='password'
/>
<NumberField name='amount' isRequired>
<NumberFieldLabel>Amount</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon className='h-4 w-4' />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon className='h-4 w-4' />
</NumberFieldDecrement>
</NumberFieldGroup>
<NumberFieldError />
</NumberField>
<button type='submit'>submit</button>
</form>
const formSchema = z.object({
username: z.string().min(2, {
message: 'Username must be at least 2 characters.',
}),
password: z.string().min(2, {
message: 'Password must be at least 2 characters.',
}),
amount: z.number().nonnegative(),
});
export default function ProfileForm() {
const form = useForm<z.infer<typeof formSchema>>({
resolver: zodResolver(formSchema),
defaultValues: {
username: '',
password: '',
amount: 0,
},
});
function onSubmit(values: z.infer<typeof formSchema>) {
const formData = new FormData();
Object.entries(values).forEach(([key, value]) => {
formData.append(key, value.toString());
});
// create(formData);
}
return (
<Form {...form}>
<form onSubmit={form.handleSubmit(onSubmit)} className='space-y-8'>
<FormField
control={form.control}
name='username'
render={({ field }) => (
<FormItem>
<FormLabel>Username</FormLabel>
<FormControl>
<Input placeholder='username' {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name='password'
render={({ field }) => (
<FormItem>
<FormLabel>Password</FormLabel>
<FormControl>
<Input type='password' placeholder='password' {...field} />
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name='amount'
render={({ field: { onChange, value } }) => (
<FormItem>
<FormLabel>Amount</FormLabel>
<FormControl>
<NumberField
onChange={onChange}
value={value}
className='gap-0'
>
<NumberFieldGroup>
<NumberFieldDecrement>
<ChevronDownIcon className='h-4 w-4' />
</NumberFieldDecrement>
<NumberFieldInput />
<NumberFieldIncrement>
<ChevronUpIcon className='h-4 w-4' />
</NumberFieldIncrement>
</NumberFieldGroup>
</NumberField>
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button type='submit'>Submit</Button>
</form>
</Form>
);
}
A NumberField's value
is empty by default, but an initial, uncontrolled, value can be provided using the defaultValue
prop. Alternatively, a controlled value can be provided using the value
prop.
value
: The current value (controlled).defaultValue
: The default value (uncontrolled).minValue
: The smallest value allowed for the input.maxValue
: The largest value allowed for the input.
let [value, setValue] = React.useState(15);
<NumberField label='defaultValue' defaultValue={8}>
<NumberFieldLabel>defaultValue</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
<NumberField label='value' value={value} onChange={setValue}>
<NumberFieldLabel>value</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
- Minimum and maximum values
The minValue
and maxValue
props can be used to limit the entered value to a specific range. The value will be clamped when the user blurs the input field. In addition, the increment and decrement buttons will be disabled when the value is within one step
value from the bounds. Ranges can be open ended by only providing either minValue
or maxValue
rather than both.
If a valid range is known ahead of time, it is a good idea to provide it to NumberField
so it can optimize the experience. For example, when the minimum value is greater than or equal to zero, it is possible to use a numeric keyboard on iOS rather than a full text keyboard (necessary to enter a minus sign).
- Step values
The step
prop can be used to snap the value to certain increments. If there is a minValue
defined, the steps are calculated starting from the minimum. For example, if minValue={2}
, and step={3}
, the valid step values would be 2, 5, 8, 11, etc. If no minValue
is defined, the steps are calculated starting from zero and extending in both directions. In other words, such that the values are evenly divisible by the step. If no step
is defined, any decimal value may be typed, but incrementing and decrementing snaps the value to an integer.
If the user types a value that is between two steps and blurs the input, the value will be snapped to the nearest step. When incrementing or decrementing, the value is snapped to the nearest step that is higher or lower, respectively. When incrementing or decrementing from an empty field, the value starts at the minValue
or maxValue
, respectively, if defined. Otherwise, the value starts from 0
.
<NumberField label='min-max' minValue={0} maxValue={10} step={3}>
<NumberFieldLabel>min-max</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
The NumberFieldInput
style can be fully customized.
<NumberField>
<NumberFieldLabel>Amount</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement className='border-blue-500'>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput className='border-blue-500 w-[500px] focus-visible:ring-blue-500' />
<NumberFieldDecrement className='border-blue-500'>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
NumberField accepts an onChange
prop which is triggered whenever the value is committed by the user. This happens on blur of the field or on interaction with the stepper functionality, arrow keys or stepper buttons.
let [value, setValue] = React.useState(0);
<NumberField label='Amount' onChange={setValue} minValue={0}>
<NumberFieldLabel>Amount</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>;
The NumberField value can be formatted by using the formatOptions
prop. formatOptions
is compatible with the option parameter of Intl.NumberFormat and is applied based on the current locale. Currently only standard notation is supported, though scientific, engineering, and compact notation may be supported in the future.
NumberField supports three numeral systems; Latin, Arabic-Indic, and Han positional decimal. Regardless of the locale, these three can be parsed from typed input. Initial rendering will appear in the default numeral system for the locale unless explicitly overridden.
The following example uses the signDisplay
option to include the plus sign for positive numbers, for example to display an offset from some value. In addition, it always displays a minimum of 1 digit after the decimal point, and allows up to 2 fraction digits. If the user enters more than 2 fraction digits, the result will be rounded.
<NumberField
label='Decimals'
defaultValue={0}
formatOptions={{
signDisplay: 'exceptZero',
minimumFractionDigits: 1,
maximumFractionDigits: 2,
}}
>
<NumberFieldLabel>Decimals</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
The style: 'percent'
option can be passed to the formatOptions
prop to treat the value as a percentage. In this mode, the value is multiplied by 100 before it is displayed, i.e. 0.45
is displayed as 45%
. The reverse is also true: when the user enters a value, the onChange
event will be triggered with the entered value divided by 100. When the percent option is enabled, the default step automatically changes to 0.01
such that incrementing and decrementing occurs by 1%
. This can be overridden with the step
prop.
<NumberField
label='Percentages'
formatOptions={{ style: 'percent' }}
minValue={0}
defaultValue={0.05}
>
<NumberFieldLabel>Percentages</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
The style: 'currency'
option can be passed to the formatOptions
prop to treat the value as a currency value. The currency
option must also be passed to set the currency code (e.g. USD
) to use. In addition, the currencyDisplay
option can be used to choose whether to display the currency symbol, currency code, or currency name. Finally, the currencySign
option can be set to accounting
to use accounting notation for negative numbers, which uses parentheses rather than a minus sign in some locales.
If you need to allow the user to change the currency, you should include a separate dropdown next to the NumberField. The NumberField itself will not determine the currency from the user input.
<NumberField
label='Currency'
defaultValue={45}
formatOptions={{
style: 'currency',
currency: 'EUR',
currencyDisplay: 'code',
currencySign: 'accounting',
}}
>
<NumberFieldLabel>Currency</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
The style: 'unit'
option can be passed to the formatOptions
prop to format the value with a unit of measurement. The unit
option must also be passed to set which unit to use (e.g. inch
). In addition, the unitDisplay
option can be used to choose whether to display the unit in long, short, or narrow format.
If you need to allow the user to change the unit, you should include a separate dropdown next to the number field. The number field itself will not determine the unit from the user input.
Note: The unit
style is not currently supported in Safari. A polyfill may be necessary.
<NumberField
label='Units'
defaultValue={4}
minValue={0}
formatOptions={{
style: 'unit',
unit: 'inch',
unitDisplay: 'long',
}}
>
<NumberFieldLabel>Units</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
The isDisabled
and isReadOnly
props can be used prevent the user from editing the value of the number field. The difference is that isReadOnly
still allows the input to be focused, while isDisabled
prevents all user interaction.
<>
<NumberField label='Disabled' isDisabled value={25}>
<NumberFieldLabel>Disabled</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
<NumberField label='Read only' isReadOnly value={28}>
<NumberFieldLabel>Read only</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
</>
For better accessibility, a label should be added to NumberField
The NumberFieldLabel
style can be fully customized. The label can be located at the top or left, the default is the top. You can also customize it as needed
<NumberField label='Amount'>
<NumberFieldLabel className='text-blue-500 text-lg'>Amount</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
You can fully customize the button style and its children.
<NumberField>
<NumberFieldLabel>Amount</NumberFieldLabel>
<NumberFieldGroup>
{/* customize the increment button's style */}
<NumberFieldIncrement className='bg-blue-500 text-white'>
{/* customize the increment button's icon */}
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
{/* customize the decrement button's style */}
<NumberFieldDecrement className='bg-blue-500 text-white'>
{/* customize the decrement button's icon */}
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
btnPosition
has two values, one is inside
, which is the default value, and the other is outside
. You can also customize it as needed
<NumberField btnPosition='outside'>
<NumberFieldLabel>Amount</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon />
</NumberFieldDecrement>
</NumberFieldGroup>
</NumberField>
<form className='flex gap-4 flex-col p-8'>
<NumberField name='amount' isRequired>
<NumberFieldLabel>
<span className="after:content-['*'] after:ml-0.5 after:text-red-500">
Amount
</span>
</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon className='h-4 w-4' />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon className='h-4 w-4' />
</NumberFieldDecrement>
</NumberFieldGroup>
<NumberFieldError />
</NumberField>
<div className='flex gap-4 justify-around'>
<button type='submit'>submit</button>
<button type='reset'>reset</button>
</div>
</form>
By default, displays the error message provided by the browser, which is localized in the user's preferred language. You can customize these messages by providing a function to the errorMessage
prop. This receives a list of error strings along with a ValidityState object describing why the field is invalid, and should return an error message to display.
<form className='flex gap-4 flex-col p-8'>
<NumberField
name='amount'
isRequired
// errorMessage='This is required'
errorMessage={(validationResult) => {
if (validationResult.validationDetails.valueMissing) {
return <p>This is required</p>;
}
}}
>
<NumberFieldLabel className=''>
<span className="after:content-['*'] after:ml-0.5 after:text-red-500">
Amount
</span>
</NumberFieldLabel>
<NumberFieldGroup className=''>
<NumberFieldIncrement>
<ChevronUpIcon className='h-4 w-4' />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon className='h-4 w-4' />
</NumberFieldDecrement>
</NumberFieldGroup>
<NumberFieldError />
</NumberField>
<div className='flex gap-4 jus tify-around'>
<button type='submit'>submit</button>
<button type='reset'>reset</button>
</div>
</form>
Custom validation is supported by providing a function to the validate
prop. This function receives the current field value, and can return a string or array of strings representing one or more error messages. These are displayed to the user after the value is committed (e.g. on blur) to avoid distracting them on each keystroke.
<form className='flex gap-4 flex-col p-8'>
<NumberField
name='amount'
validate={(value) => {
if (value < 0) {
return 'value must be greater than 0';
}
}}
>
<NumberFieldLabel>
<span className="after:content-['*'] after:ml-0.5 after:text-red-500">
Amount
</span>
</NumberFieldLabel>
<NumberFieldGroup>
<NumberFieldIncrement>
<ChevronUpIcon className='h-4 w-4' />
</NumberFieldIncrement>
<NumberFieldInput />
<NumberFieldDecrement>
<ChevronDownIcon className='h-4 w-4' />
</NumberFieldDecrement>
</NumberFieldGroup>
<NumberFieldError />
</NumberField>
<div className='flex gap-4 justify-around'>
<button type='submit'>submit</button>
<button type='reset'>reset</button>
</div>
</form>
Name | Type | Default | Descriptiion |
---|---|---|---|
className |
string | — | className for NumberField's container |
Name | Type | Default | Descriptiion |
---|---|---|---|
name |
string | — | The name of input |
value |
number | — | The current value (controlled). |
defaultValue |
number | — | The default value (uncontrolled). |
minValue |
number | — | The smallest value allowed for the input. |
maxValue |
number | — | The largest value allowed for the input. |
step |
number | — | The amount that the input value changes with each increment or decrement "tick". |
formatOptions |
Intl.NumberFormatOptions | — | Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. |
autoFocus |
boolean | — | Whether the element should receive focus on render. |
placeholder |
string | — | Temporary text that occupies the text input when it is empty. |
locale |
string | the current locale | The locale that should be used for parsing. |
isDisabled |
boolean | — | Whether the input is disabled. |
isReadOnly |
boolean | — | Whether the input can be selected but not changed by the user. |
isWheelDisabled |
boolean | — | Enables or disables changing the value with scroll. |
onChange |
(value: T) => void | — | Handler that is called when the value changes. |
onFocus |
(e: FocusEvent) => void | — | Handler that is called when the element receives focus. |
onBlur |
(e: FocusEvent) => void | — | Handler that is called when the element loses focus. |
onFocusChange |
(isFocused: boolean) => void | — | Handler that is called when the element's focus status changes. |
onKeyDown |
(e: KeyboardEvent) => void | — | Handler that is called when a key is pressed. |
onKeyUp |
(e: KeyboardEvent) => void | — | Handler that is called when a key is released. |
onCopy |
ClipboardEventHandler<HTMLInputElement> | — | Handler that is called when the user copies text. See MDN. |
onCut |
ClipboardEventHandler<HTMLInputElement> | — | Handler that is called when the user cuts text. See MDN. |
onPaste |
ClipboardEventHandler<HTMLInputElement> | — | Handler that is called when the user pastes text. See MDN. |
onSelect |
ReactEventHandler<HTMLInputElement> | — | Handler that is called when text in the input is selected. See MDN. |
onBeforeInput |
FormEventHandler<HTMLInputElement> | — | Handler that is called when the input value is about to be modified. See MDN. |
onInput |
FormEventHandler<HTMLInputElement> | — | Handler that is called when the input value is modified. See MDN. |
onCompositionStart |
CompositionEventHandler<HTMLInputElement> | — | Handler that is called when a text composition system starts a new text composition session. See MDN. |
onCompositionEnd |
CompositionEventHandler<HTMLInputElement> | — | Handler that is called when a text composition system completes or cancels the current text composition session. See MDN. |
onCompositionUpdate |
CompositionEventHandler<HTMLInputElement> | — | Handler that is called when a new character is received in the current text composition session. See MDN. |
isRequired |
boolean | — | Whether user input is required on the input before form submission. |
validationBehavior |
'aria' | 'native' |
'native' |
Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
validate |
(value: number) => ValidationError | true | null | undefined | — | This is a function for custom validation rules and returns error message, if a given value is invalid. |
errorMessage |
ReactNode | (v: ValidationResult) => ReactNode | — | Customizing error messages. By default, displays the error message provided by the browser, which is localized in the user's preferred language. You can customize these messages by providing a function to the errorMessage prop. This receives a list of error strings along with a ValidityState object describing why the field is invalid, and should return an error message to display. |
Name | Type | Default | Descriptiion |
---|---|---|---|
btnPosition |
"inside" | "outside" | "inside" | Set the position of the button. |
Name | Type | Default | Descriptiion |
---|---|---|---|
labelPosition |
"left" | "top" | "top" | Set the position of the label. |
Name | Type | Default | Descriptiion |
---|---|---|---|
id |
string | — | A custom id for the input. |
aria-label |
string | — | A custom aria-label for the input, increment button, decrement button. If the value is amount , input is aria-label="amount" , increment button is aria-label="Increment amount" , decrement button is aria-label="Decrement amount" . |
aria-details |
string | — | A custom aria-details for the input. Identifies the element (or elements) that provide a detailed, extended description for the object. |
decrementAriaLabel |
string | — | A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used. |
incrementAriaLabel |
string | — | A custom aria-label for the increment button. If not provided, the localized string "Increment" is used. |
Name | Type | Default | Descriptiion |
---|---|---|---|
className |
string | undefined | — | The className of the NumberFieldGroup . |
children |
React.ReactNode | — | The children of the NumberFieldGroup . |
Name | Type | Default | Descriptiion |
---|---|---|---|
className |
string | undefined | — | The className of the increment button. |
children |
React.ReactNode | ChevronUpIcon of lucide-react |
The children of the increment button. |
Name | Type | Default | Descriptiion |
---|---|---|---|
className |
string | undefined | — | The className of the decrement button. |
children |
React.ReactNode | ChevronDownIcon of lucide-react |
The children of the decrement button. |
Name | Type | Default | Descriptiion |
---|---|---|---|
className |
string | undefined | — | The className of the NumberFieldLabel . |
children |
React.ReactNode | — | The children of the NumberFieldLabel . |
Name | Type | Default | Descriptiion |
---|---|---|---|
className |
string | undefined | — | The className of the NumberFieldError . |