Number Field

InstallCopy Anchor Link

pnpm exec vegastack-design verify number-field

pnpm dlx shadcn@4.21.0 add @vegastack/number-field

UsageCopy Anchor Link

import { NumberField } from "@/components/ui/number-field";

<NumberField aria-label="Quantity" defaultValue={2} min={0} max={99} />;

NumberField wraps Base UI's NumberField: locale-aware parsing and formatting (format: Intl.NumberFormatOptions + locale), min/max/step with snapOnStep, keyboard stepping, and wheel scrubbing.

Everything it renders is imported, not restated: InputGroup is the bordered box — border, focus border, invalid hairline, disabled wash — InputGroupInput is Input flattened into it, prefix and suffix are InputGroupAddon slots, and each − / + stepper is an InputGroupButton, which is Button in its ghost variant.

The one thing this component adds is the layout: the steppers flank the field at its full height rather than stacking as half-height spinners, so each pointer target clears 24px inside a 32px control without an invisible hit area. There is no control-height scale — the box is InputGroup's 32px, and a caller who needs another height passes a height class in className.

What lives elsewhere, and why:

ExamplesCopy Anchor Link

MoneyCopy Anchor Link

Money is a format prop, not a separate component: format={{ style: "currency", currency: "USD" }}. The currency-code Select drops into the suffix slot.

One recipe belongs to your field layer, not this component: minor units. If your API stores integer cents, convert at the boundary — the component works in display units:

<NumberField
  aria-label="Amount"
  value={amountInCents / 100}
  onValueChange={(v) => setAmountInCents(Math.round((v ?? 0) * 100))}
  format={{ style: "currency", currency: "USD" }}
/>

Units and statesCopy Anchor Link

A percent format, the unit suffix, hideControls, disabled, and the invalid destructive border. Wrap the field in a Field to pair that border with a message. Click or Tab into a field to see the focus state: the box's border darkens subtly and nothing fills; the invalid field keeps its destructive border while focused.

Inside a FieldCopy Anchor Link

Inside a Field the inner <input> — never the group — takes the label, the rendered description and error ids, and aria-invalid. Outside one, aria-describedby, aria-labelledby and id also land on the input.

API ReferenceCopy Anchor Link

All Base UI NumberField.Root props pass through: format, locale, min, max, allowOutOfRange, step / largeStep / smallStep, snapOnStep, allowWheelScrub, readOnly, required, onValueChange, onValueCommitted, and native form integration via name.

AccessibilityCopy Anchor Link

• The inner input must carry an accessible name — pass aria-label (or label it through a wrapping Field).
• The − / + steppers are full-height, ≥24px pointer targets with accessible names ("Decrease" / "Increase"); keyboard users step with the arrow keys instead, so the buttons add no tab stops beyond Base UI's defaults.
• Focus uses the text-entry affordance: while the input inside it has focus, the InputGroup box's border darkens subtly (border-ring/50, easing in over 150ms) and no background changes — text entry's exception to FOC-14 (MK 2026-09-27). An invalid field keeps its destructive border while focused. The steppers are buttons: they keep the global :focus-visible background tint, pulled inside the clipping box (FOC-9).

Do / Don'tCopy Anchor Link