Number field

When to use #

Use it for

Seats, quantities and counts with a minimum and maximum.
You want unit text that follows the value.

Skip it when

The number is a money amount; use a money field.
The range is wide and imprecise; use a slider.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/number-field.json

Adds its 5 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx

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

export function SeatCount() {
  const [seats, setSeats] = useState(3);
  return (
    <div className="w-full max-w-xs">
      <NumberField label="Seats" value={seats} min={1} max={8} scrub suffix={(count) => (count === 1 ? " seat" : " seats")} onValueChange={setSeats} />
    </div>
  );
}

API reference #

NumberField

component

PropTypeDefault

label *string—

valuenumber—

defaultValuenumber—

minnumber0

maxnumber100

stepnumber1

prefixstring""

suffixstring | ((value: number) => string)—

scrubbooleanfalse

disabledboolean—

namestring—

idstring—

onValueChange((value: number) => void)—

classNamestring—

It exposes status and spinbutton semantics, with aria-label, aria-disabled, aria-hidden, aria-valuenow, aria-valuemin and aria-valuemax kept in step with state. Changes that matter are announced through a live region.

KeyBehaviour

↑Moves to the previous item or value.

↓Moves to the next item or value.

HomeJumps to the first item or the minimum.

EndJumps to the last item or the maximum.

EnterActivates the focused control.

Motion #

It checks prefers-reduced-motion itself and settles immediately instead of travelling. Every state is still reachable.