---
title: "NumberField"
description: "An input for a non-clinical number with increment and decrement steppers, built on Base UI NumberField."
url: "https://opsinjs.pensievelabs.org/docs/components/number-field"
source: "https://opsinjs.pensievelabs.org/docs/components/number-field.md"
section: "Components"
status: "shipped"
kind: "component"
category: "actions-and-forms"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["stepper input", "quantity input"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="number-field"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured: the hairline, the stepper glyphs, the input ink and the muted disabled ink are argued from their roles, not checked.&#x22;,
  &#x22;Nobody has heard the field in a screen reader, so whether a named spinbutton with two named steppers arrives in the expected order is reasoned, not tested.&#x22;,
  &#x22;A stepper disabled at a bound is drawn in muted ink alone, and whether reaching a bound is announced to assistive technology has not been tested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="number-field" unbuilt="false" importPath="@/components/ui/number-field" dependencies="[&#x22;@base-ui/react&#x22;, &#x22;lucide-react&#x22;]" />

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

```tsx
<NumberField
  label="Number of copies"
  value={copies}
  onValueChange={setCopies}
  min={1}
  max={10}
  step={1}
/>
```

## Examples [#examples]

<ComponentPreview name="number-field" />

### A quantity [#a-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.

<ComponentPreview name="number-field-a-quantity" kind="example" align="start" />

### With bounds [#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.

<ComponentPreview name="number-field-with-bounds" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A plain quantity or count with no clinical meaning, such as the number of copies to print.&#x22;,
  &#x22;A value the reader nudges one at a time as readily as types it.&#x22;,
  &#x22;A bounded count where a floor and a ceiling the product owns keep the reader inside a range.&#x22;,
]"
  avoid="[
  { case: &#x22;It is a clinical measurement, which carries a unit, needs an out-of-range warning and is typed in whole.&#x22;, instead: &#x22;reading-input&#x22; },
  { case: &#x22;The number is typed once and never nudged, such as a year or a reference code.&#x22;, instead: &#x22;field&#x22; },
]"
/>

## Accessibility [#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.

<KeyboardTable
  name="number-field"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus into the field, onto the input&#x22;,
    notes: &#x22;The buttons are reachable with Tab too.&#x22;,
  },
  {
    keys: &#x22;Arrow Up, Arrow Down&#x22;,
    action: &#x22;Steps the value up or down by step&#x22;,
    notes: &#x22;Stops at max going up, min going down.&#x22;,
  },
  {
    keys: &#x22;Page Up, Page Down&#x22;,
    action: &#x22;Steps by a larger amount&#x22;,
    notes: &#x22;Base UI's large step, for crossing a bounded range quickly.&#x22;,
  },
  {
    keys: &#x22;Home, End&#x22;,
    action: &#x22;Jumps to min or max&#x22;,
    notes: &#x22;Only where that bound is set.&#x22;,
  },
  {
    keys: &#x22;Enter&#x22;,
    action: &#x22;Commits the typed value&#x22;,
    notes: &#x22;Inside a form it also submits, the same as any text input.&#x22;,
  },
]"
/>

<ContrastReport component="number-field" />

## Props interface [#props-interface]

<PropsTable name="NumberFieldProps" />

`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.
