Number Input

Basic

A production-ready numeric stepper with +/− buttons, keyboard navigation, min/max clamping, precision control, and animated digit roll transitions.

<NumberInput defaultValue={0} min={0} max={100} /><NumberInput defaultValue={42} min={0} max={999} step={5} />

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add number-input

pnpm dlx @work-rjkashyap/unified-ui add number-input

npx @work-rjkashyap/unified-ui add number-input

bunx @work-rjkashyap/unified-ui add number-input

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { NumberInput } from "@work-rjkashyap/unified-ui";

Basic Usage

NumberInput works uncontrolled with defaultValue, or controlled with value + onChange.

{
	/* Uncontrolled */
}
<NumberInput defaultValue={10} min={0} max={100} />;

{
	/* Controlled */
}
const [qty, setQty] = useState(1);
<NumberInput value={qty} onChange={setQty} min={1} max={50} />;

Sizes

<NumberInput defaultValue={5} size="sm" min={0} max={99} /><NumberInput defaultValue={5} size="md" min={0} max={99} /><NumberInput defaultValue={5} size="lg" min={0} max={99} />

Variants

<NumberInput defaultValue={10} variant="default" min={0} max={100} /><NumberInput defaultValue={10} variant="primary" min={0} max={100} />

Step

Control the increment/decrement amount with step. Defaults to 1.

<NumberInput defaultValue={0} step={1} min={0} max={10} /><NumberInput defaultValue={0} step={5} min={0} max={100} /><NumberInput defaultValue={0} step={10} min={0} max={100} />

Hold Shift while pressing arrow keys to step by 10× the current step value.

Precision (Decimals)

Use precision to allow and display decimal values. Pair with step for consistent increments.

{/* Currency */}<NumberInputdefaultValue={9.99}precision={2}step={0.01}min={0}max={99.99}/>{/* Half-steps */}<NumberInputdefaultValue={3.5}precision={1}step={0.5}min={0}max={10}/>

Custom Format

Supply a formatValue function to display the number with a prefix, suffix, or custom notation.

{/* Percentage */}<NumberInputdefaultValue={50}min={0}max={100}formatValue={(v) => `${v}%`}/>{/* Currency */}<NumberInputdefaultValue={1200}min={0}max={10000}step={100}formatValue={(v) => `$${v.toLocaleString()}`}/>

Disabled & Read-Only

{
	/* Disabled — no interaction */
}
<NumberInput defaultValue={42} disabled />;

{
	/* Read-only — visible but not editable */
}
<NumberInput defaultValue={42} readOnly />;

Controlled

const [quantity, setQuantity] = useState(1);

<div className="flex flex-col gap-2">
	<label className="text-sm font-medium">Quantity</label>
	<NumberInput
		value={quantity}
		onChange={setQuantity}
		min={1}
		max={99}
		step={1}
		aria-label="Quantity"
	/>
	<p className="text-xs text-muted-foreground">
		Total: ${(quantity * 29.99).toFixed(2)}
	</p>
</div>;

In a Form

A typical quantity selector inside a product form.

<form className="flex flex-col gap-4">
	<div className="flex flex-col gap-1.5">
		<label className="text-sm font-medium">Quantity</label>
		<NumberInput
			defaultValue={1}
			min={1}
			max={99}
			aria-label="Item quantity"
		/>
	</div>

	<div className="flex flex-col gap-1.5">
		<label className="text-sm font-medium">Discount (%)</label>
		<NumberInput
			defaultValue={0}
			min={0}
			max={100}
			step={5}
			formatValue={(v) => `${v}%`}
			aria-label="Discount percentage"
		/>
	</div>
</form>

Props

Keyboard Navigation

Motion

The value display uses the numberRoll preset — digits animate with a vertical slide (y: 6px → 0, opacity: 0 → 1) on each change via AnimatePresence. This gives a tactile "odometer" feel. The animation is skipped when prefers-reduced-motion is active.

Accessibility

• Root element uses role="spinbutton" with aria-valuenow, aria-valuemin, aria-valuemax, aria-disabled, and aria-readonly.
• + and − buttons have descriptive aria-label attributes.
• The value display button announces "Current value: X, press to edit" for screen readers.
• In edit mode, the <input> uses inputMode="decimal" for mobile numeric keyboards.
• Min/max clamping is enforced on blur — invalid entries are silently corrected.
• All keyboard interactions are WCAG AA compliant for spinbutton role.

Design Tokens