import { Field, FieldLabel } from "@/components/ui/field";import { NumberInput } from "@/components/ui/number-input";
export default function NumberInputBasic() { return ( <Field className="w-28"> <FieldLabel>Seats</FieldLabel> <NumberInput defaultValue={3} min={1} max={10} /> </Field> );}- Completed:Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json - Completed:Add number-input
pnpm dlx shadcn@latest add @jarvis/number-input
Usage
import { Field, FieldLabel } from "@/components/ui/field";import { NumberInput } from "@/components/ui/number-input";
export function GuestsField() { return ( <Field> <FieldLabel>Guests</FieldLabel> <NumberInput defaultValue={2} min={1} max={12} /> </Field> );}A FieldLabel in the same Field labels the input. Without a visible label,
give NumberInput an aria-label.
Without children, NumberInput renders its input and stepper buttons. To customize them, such as
to put a currency symbol before the number or a NumberInputScrubArea around the label, compose
the parts yourself:
import { NumberInput, NumberInputDecrement, NumberInputGroup, NumberInputIncrement, NumberInputInput,} from "@/components/ui/number-input";
export function PriceInput() { return ( <NumberInput aria-label="Price" defaultValue={20}> <NumberInputGroup> <span>$</span> <NumberInputInput /> <NumberInputDecrement /> <NumberInputIncrement /> </NumberInputGroup> </NumberInput> );}Either way, NumberInput passes its aria-label and placeholder to its NumberInputInput.
Composition
Examples
Formatting
format takes Intl.NumberFormat (opens in a new tab)
options, for decimals, percentages or units.
import { NumberInput, NumberInputGroup, NumberInputInput, NumberInputDecrement, NumberInputIncrement,} from "@/components/ui/number-input";
export default function NumberInputFormatting() { return ( <div className="flex flex-wrap items-center gap-3"> <NumberInput defaultValue={50} min={5} step={5} format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }} className="w-36" > <NumberInputGroup> <span>$</span> <NumberInputInput aria-label="Amount in USD" /> <NumberInputDecrement /> <NumberInputIncrement /> </NumberInputGroup> </NumberInput> <NumberInput defaultValue={0.15} min={0} max={1} step={0.05} format={{ style: "percent" }} className="w-28" aria-label="Discount" /> </div> );}Scrub area
Wrap the label in a NumberInputScrubArea to change the value by dragging it sideways.
import { Field, FieldLabel } from "@/components/ui/field";import { NumberInput, NumberInputGroup, NumberInputInput, NumberInputDecrement, NumberInputIncrement, NumberInputScrubArea,} from "@/components/ui/number-input";
export default function NumberInputScrub() { return ( <div className="flex flex-wrap items-center gap-3"> <Field className="w-32"> <NumberInput defaultValue={240} min={0} max={1200}> <NumberInputScrubArea> <FieldLabel>Width</FieldLabel> </NumberInputScrubArea> <NumberInputGroup className="pr-2"> <NumberInputInput /> <span>px</span> </NumberInputGroup> </NumberInput> </Field> <Field className="w-32"> <NumberInput defaultValue={0.8} min={0} max={1} step={0.01} format={{ style: "percent" }}> <NumberInputScrubArea> <FieldLabel>Opacity</FieldLabel> </NumberInputScrubArea> <NumberInputGroup> <NumberInputInput /> <NumberInputDecrement /> <NumberInputIncrement /> </NumberInputGroup> </NumberInput> </Field> </div> );}Large
Set size="lg" on NumberInput for a taller input, or size="sm" for a shorter one.
import * as React from "react";
import { Button } from "@/components/ui/button";import { NumberInput, NumberInputGroup, NumberInputInput, NumberInputDecrement, NumberInputIncrement,} from "@/components/ui/number-input";import { Select, SelectContent, SelectItem, SelectTrigger } from "@/components/ui/select";import { toast } from "@/components/ui/toast";
const cards = { visa: "Visa •• 7391", amex: "Amex •• 1008" };
export default function NumberInputLarge() { const [amount, setAmount] = React.useState<number | null>(50);
return ( <div className="flex flex-wrap items-center gap-3"> <NumberInput value={amount} onValueChange={setAmount} min={5} max={500} step={5} format={{ minimumFractionDigits: 2, maximumFractionDigits: 2 }} size="lg" className="w-40" > <NumberInputGroup> <span>$</span> <NumberInputInput aria-label="Amount in USD" /> <NumberInputDecrement /> <NumberInputIncrement /> </NumberInputGroup> </NumberInput> <Select items={cards} defaultValue="visa"> <SelectTrigger size="lg" aria-label="Payment method" /> <SelectContent> {Object.entries(cards).map(([value, label]) => ( <SelectItem key={value} value={value}> {label} </SelectItem> ))} </SelectContent> </Select> <Button variant="secondary" size="lg" disabled={amount === null} onClick={() => toast.add({ title: "Funds added", type: "success" })} > Add ${amount === null ? "" : amount.toFixed(2)} </Button> </div> );}Steppers on either side
Put NumberInputDecrement before NumberInputInput to place the buttons on either side of the
value. To center the value with a label after it, size the input to its value with
field-sizing-content, and push the buttons to the edges with mr-auto and ml-auto. In browsers
without field-sizing, the input's size attribute sets its width in characters.
import { NumberInput, NumberInputDecrement, NumberInputGroup, NumberInputIncrement, NumberInputInput,} from "@/components/ui/number-input";
export default function NumberInputSteppersEitherSide() { return ( <NumberInput aria-label="Seats" defaultValue={8} min={2} max={12} size="lg" className="w-48"> <NumberInputGroup> <NumberInputDecrement className="mr-auto" /> <NumberInputInput size={2} className="field-sizing-content w-auto flex-none self-baseline text-right" /> <span className="self-baseline">seats</span> <NumberInputIncrement className="ml-auto" /> </NumberInputGroup> </NumberInput> );}Display
Set variant="display" to show the value in large type between round stepper buttons, for a
Sheet or Card built around a single number. To label the
number, compose the parts and add a caption under NumberInputInput.
import { NumberInput, NumberInputDecrement, NumberInputGroup, NumberInputIncrement, NumberInputInput,} from "@/components/ui/number-input";
export default function NumberInputDisplay() { return ( <NumberInput variant="display" aria-label="Cups of water per day" defaultValue={8} min={1} max={16} > <NumberInputGroup> <NumberInputDecrement /> <div className="flex flex-col items-center"> <NumberInputInput /> <span className="text-2xs text-faint">cups per day</span> </div> <NumberInputIncrement /> </NumberInputGroup> </NumberInput> );}Disabled
import { NumberInput } from "@/components/ui/number-input";
export default function NumberInputDisabled() { return <NumberInput defaultValue={12} disabled className="w-28" aria-label="Quantity" />;}Read-only
import { NumberInput } from "@/components/ui/number-input";
export default function NumberInputReadOnly() { return <NumberInput defaultValue={12} readOnly className="w-28" aria-label="Quantity" />;}Invalid
Set invalid on the Field and explain the problem with a FieldError.
import { Field, FieldError, FieldLabel } from "@/components/ui/field";import { NumberInput } from "@/components/ui/number-input";
export default function NumberInputInvalid() { return ( <Field invalid className="w-40"> <FieldLabel>Quantity</FieldLabel> <NumberInput defaultValue={0} min={0} /> <FieldError>Order at least one.</FieldError> </Field> );}Props
Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.
NumberInput
| Prop | Type | Default |
|---|---|---|
idThe id of the input element. | string | — |
minThe minimum value of the input element. | number | — |
maxThe maximum value of the input element. | number | — |
allowOutOfRangeWhen true, direct text entry may be outside the | boolean | false |
smallStepThe small step value of the input element when incrementing while the alt key is held.
Snaps to multiples of this value when | number | 0.1 |
stepAmount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area.
To always enable step validation on form submission, specify the | number | "any" | 1 |
largeStepThe large step value of the input element when incrementing while the shift key is held.
Snaps to multiples of this value when | number | 10 |
requiredWhether the user must enter a value before submitting a form. | boolean | false |
disabledWhether the component should ignore user interaction. | boolean | false |
readOnlyWhether the user should be unable to change the field value. | boolean | false |
nameIdentifies the field when a form is submitted. | string | — |
formIdentifies the form that owns the hidden input. Useful when the number field is rendered outside the form. | string | — |
valueThe raw numeric value of the field. | number | null | — |
defaultValueThe uncontrolled value of the field when it's initially rendered. To render a controlled number field, use the | number | — |
allowWheelScrubWhether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input. | boolean | false |
snapOnStepWhether the value should snap to the nearest step when incrementing or decrementing. | boolean | false |
formatOptions to format the input value. | Intl.NumberFormatOptions | — |
onValueChangeCallback fired when the number value changes. The
| ((value: number | null, eventDetails: NumberField.Root.ChangeEventDetails) => void) | — |
onValueCommittedCallback function that is fired when the value is committed.
It runs later than
It runs simultaneously with Warning: This is a generic event not a change event. | ((value: number | null, eventDetails: NumberField.Root.CommitEventDetails) => void) | — |
localeThe locale of the input element. Defaults to the user's runtime locale. | Intl.LocalesArgument | "en-US" |
inputRefA ref to access the hidden input element. | React.Ref<HTMLInputElement> | — |
aria-labelDefines a string value that labels the current element.
Labels the input when there's no | string | — |
aria-labelledbyIdentifies the element (or elements) that labels the current element.
The | string | — |
variant
| "default" | "display" | "default" |
sizeThe height: | "default" | "lg" | "sm" | "default" |
placeholderThe input's placeholder. | string | — |
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: NumberFieldRootState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: NumberFieldRootState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, NumberFieldRootState> | React.ReactElement | — |
NumberInputGroup
| Prop | Type | Default |
|---|---|---|
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: NumberFieldGroupState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: NumberFieldGroupState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, NumberFieldGroupState> | React.ReactElement | — |
NumberInputInput
| Prop | Type | Default |
|---|---|---|
aria-roledescriptionA user-friendly description of the input's role for assistive tech. This is a role
description, not an accessible name — use | string | 'Number field' |
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: NumberFieldInputState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: NumberFieldInputState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState> | React.ReactElement | — |
NumberInputDecrement
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native | boolean | true |
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: NumberFieldDecrementState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: NumberFieldDecrementState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, NumberFieldDecrementState> | React.ReactElement | — |
NumberInputIncrement
| Prop | Type | Default |
|---|---|---|
nativeButtonWhether the component renders a native | boolean | true |
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: NumberFieldIncrementState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: NumberFieldIncrementState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, NumberFieldIncrementState> | React.ReactElement | — |
NumberInputScrubArea
| Prop | Type | Default |
|---|---|---|
directionCursor movement direction in the scrub area. | "horizontal" | "vertical" | "horizontal" |
pixelSensitivityDetermines how many pixels the cursor must move before the value changes. A higher value will make scrubbing less sensitive. | number | 2 |
teleportDistanceIf specified, determines the distance that the cursor may move from the center of the scrub area before it will loop back around. | number | — |
classNameCSS class applied to the element, or a function that returns a class based on the component's state. | string | ((state: NumberFieldScrubAreaState) => string | undefined) | — |
styleStyle applied to the element, or a function that returns a style object based on the component's state. | React.CSSProperties | ((state: NumberFieldScrubAreaState) => React.CSSProperties | undefined) | — |
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaState> | React.ReactElement | — |