Components
NumberField
An input for a non-clinical number with increment and decrement steppers, built on Base UI NumberField.
Usage
pnpm dlx shadcn@latest add @opsinjs/number-field
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { NumberField } from "@/components/ui/number-field"<NumberField
label="Number of copies"
value={copies}
onValueChange={setCopies}
min={1}
max={10}
step={1}
/>Examples
number-field · base base · style base-lyraOpen under the product themeA quantity
A reader sets how many copies to print, stepping with the buttons or typing.
label names the count, which is fictional and carries no unit.
number-field-a-quantity · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { NumberField } from "@/components/ui/number-field"
export default function NumberFieldAQuantity() {
const [copies, setCopies] = useState<number | null>(3)
return (
<NumberField
label="Number of copies"
value={copies}
onValueChange={setCopies}
min={1}
step={1}
/>
)
}With bounds
min and max fix the range and step sets how far one press moves. The
decrement button disables at the floor and the increment button at the ceiling.
number-field-with-bounds · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { NumberField } from "@/components/ui/number-field"
export default function NumberFieldWithBounds() {
const [seats, setSeats] = useState<number | null>(4)
return (
<NumberField
label="People sharing this entry"
value={seats}
onValueChange={setSeats}
min={1}
max={8}
step={1}
/>
)
}When to use it
Use it when
- A plain quantity or count with no clinical meaning, such as the number of copies to print.
- A value the reader nudges one at a time as readily as types it.
- A bounded count where a floor and a ceiling the product owns keep the reader inside a range.
Do not use it when
- It is a clinical measurement, which carries a unit, needs an out-of-range warning and is typed in whole.Use
reading-inputinstead. - The number is typed once and never nudged, such as a year or a reference code.Use
fieldinstead.
Accessibility
The audit found no axe violation and no loss at 320px reflow, with focus visible
and a 44px target floor. Icons are aria-hidden, there is neither colour axis
nor a colour-only state, type uses role tokens with no px size, and Base UI
supplies its own keyboard and names. The input could be named only through
aria-label, so the audit made the wrapper also forward id and aria-labelledby,
suppressing the redundant aria-label when a visible label is wired so it wins
the name and Label in Name holds. label stays the required default, so the
change is additive.
Residual items.
- The default still names the input through
aria-label. A persistent visible label is a recommended enhancement, deferred to one central repair across the input wrappers. - Base UI hard-codes
autoComplete="off", acceptable for a count with no WCAG token, and surfaces no error text, since it clamps to bounds and owns validation. - Every contrast pair, including the disabled ink at a bound, is unmeasured, so the report below stands in.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus into the field, onto the input | The buttons are reachable with Tab too. |
| Arrow Up, Arrow Down | Steps the value up or down by step | Stops at max going up, min going down. |
| Page Up, Page Down | Steps by a larger amount | Base UI's large step, for crossing a bounded range quickly. |
| Home, End | Jumps to min or max | Only where that bound is set. |
| Enter | Commits the typed value | Inside a form it also submits, the same as any text input. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from NumberFieldProps in registry/bases/base/number-field.tsx.
value and onValueChange make this a controlled component with no internal
value state. The caller stores the number, or null when the field is empty.
label is required, because a spinbutton needs an accessible name. A min
above max raises a development warning. min, max and step are the
count's own bounds, never a clinical range.