Number Stepper

Usage

NumberStepper is for a bounded quantity you both nudge and type: a cart quantity, a guest count, a zoom level, a price. It is a React Aria NumberField underneath, so stepping, clamping, step rounding, hold-to-repeat and the formatOptions round trip are all the library's.

The value rolls, and the field is still typeable: Value and Input share a grid cell and swap when you start editing.

Anatomy

Import the NumberStepper component and access all parts using dot notation.

import {NumberStepper} from "@blakeui/pro-react";

<NumberStepper>
  <NumberStepper.Label />
  <NumberStepper.Group>
    <NumberStepper.DecrementButton />
    <NumberStepper.Value />
    <NumberStepper.Input />
    <NumberStepper.IncrementButton />
  </NumberStepper.Group>
  <NumberStepper.Description />
</NumberStepper>;

Write the children in this order whatever the layout, and keep Value immediately before Input — the swap between them is an adjacent-sibling rule.

Guest Picker

Controlled

Custom Icons

Custom Value

Disabled

Min Max Values

Reversed Layout

Sizes

With Custom Buttons

With Format Options

With Label

With Step

CSS Classes

The root here is .number-stepper, deliberately not .number-field. @blakeui/react already ships a NumberField and @blakeui/styles owns .number-field, whose group is a hard-coded grid-template-columns: 40px 1fr 40px with field elevation and no size scale. Free and Pro share no class name here, the same split EmptyState (free) and EmptyPanel (Pro) already settled. Nothing in the free layer targets these names, so every selector below is a single class rather than the doubled-up specificity a restyled free component would need.

The shape is a segmented pill: a tinted track with two raised circular buttons inset into it. That treatment is not invented here — it is what the Data Grid's editable-cells rollout stepper already ships and what the docs viewport toggle uses.

Base Classes

• .number-stepper — The root. Declares every custom property below and stacks label, group and message as a flex column with a 6px gap. Hugs its content by default. Carries data-slot="number-stepper".
• .number-stepper--full-width — Stretches the root to fill its container.
• .number-stepper__group — The pill track, and the only box the modifiers land on. display: grid, fully rounded, var(--number-stepper-inset) of padding, background-color: var(--number-stepper-track). Flat: no border, no shadow — the elevation in this component sits on the buttons.

Layout Classes

Both land on the group, and both are pure re-placement — the DOM order is always decrement, value, input, increment.

• .number-stepper__group--default — grid-template-areas: "decrement value increment". The default.
• .number-stepper__group--reversed — grid-template-areas: "increment value decrement". The same three columns, the two buttons swapped.

minmax(0, 1fr) rather than a bare 1fr on the value column is what keeps a long formatted value — a currency string at a wide locale — from pushing the buttons out of the track; 1fr floors at the content's min-content width.

Size Classes

Each retunes the button diameter, the type size and the icon together. The button is a circle, so --number-stepper-control is its target on both axes and every scale clears 24px.

• .number-stepper__group--sm — 24px button, 0.8125rem type, 14px icon.
• .number-stepper__group--md — 28px button, 0.875rem type, 16px icon. The default.
• .number-stepper__group--lg — 32px button, 0.9375rem type, 18px icon.

Element Classes

• .number-stepper__label — The field's accessible name, a real <label> React Aria ties to the input, so pressing it focuses the field.
• .number-stepper__value — The display cell. Shares its grid area with the input, which is how the two overlap without absolute positioning — the input is the value's sibling, so position: absolute would resolve against the nearest positioned ancestor and escape the cell entirely. aria-hidden.
• .number-stepper__odometer — The rolling number itself, rendered by the shared Odometer. Its wheels are clipped by --ac-od-step, which the root re-declares because that variable has no :root definition.
• .number-stepper__suffix — Static text beside the digits — a unit or a symbol. It does not roll, because a unit is not a number. Also carries a fully custom value when Value is given children.
• .number-stepper__input — The typeable field. Stripped bare — no border, no background, no shadow, no outline — because the track carries all of those. font-variant-numeric: tabular-nums, and z-index: 1 so it stays the hit target while a Value sits under it.
• .number-stepper__increment-button / .number-stepper__decrement-button — The two buttons, each claiming its grid area. These render the @blakeui/react Button, so the shape is ours and the paint can be its. Left unstyled they take the raised-circle treatment; given a variant they take that variant's fill and the raised-circle rule backs off through :not([data-variant]).
• .number-stepper__icon — The glyph wrapper, and the element the press animation runs on. Nothing in CSS may set scale or transform here: motion owns that property on this element.
• .number-stepper__description — The supporting line, var(--muted) at 0.75rem. Tied to the input by aria-describedby.

States

State is carried by data attributes React Aria already sets, plus the buttons' own real disabled attribute — no extra classes.

• [data-disabled="true"] on the root — drops the whole control to opacity: 0.5 and sets cursor: not-allowed on all three parts. The input leaves the tab order with it.
• :disabled on a button — React Aria reporting that this direction has run out: at a bound, under isReadOnly, or under a disabled root. It is a real disabled attribute, not a class: the button stops dispatching press, cannot take focus even programmatically, and announces as disabled. It also loses its elevation, because a raised pill that cannot be pressed is a lie about what it does.
• [data-hovered="true"] / [data-pressed="true"] on an enabled button — a brightness() shift, which works on the default circle and on any variant alike.
• Focus — the ring goes on the track when the input is focused, because the input fills a cell of the pill and ringing the bare cell would draw a rectangle inside a capsule. A focused button keeps its own ring.

Both stepper buttons carry tabindex="-1" at all times — that is React Aria's doing, and it is the standard keyboard model for this control: the input is the single tab stop and the arrow keys do the stepping, so tabbing never lands on a button whether it is disabled or not.

CSS Variables

All declared on .number-stepper and re-declared by the size modifiers, so overriding one on the root retunes the whole component.

• --number-stepper-control — The button's diameter. 24px / 28px / 32px.
• --number-stepper-inset — The track's padding around the buttons. 4px.
• --number-stepper-gap — The gap between the cells. 4px.
• --number-stepper-font-size — Type size for the label and the value.
• --number-stepper-icon-size — The glyph.
• --number-stepper-value-width — The value cell's minimum width, which is what keeps the pill from resizing as digits are gained.
• --ac-od-step — The Odometer's wheel-cell height and per-cell translate step, in one variable so the roll distance stays locked to the cell. 1.25em, the same value the chart roots use. It has no global :root definition, so a component reusing the Odometer must re-declare it or the wheels render unclipped.
• --number-stepper-track / --number-stepper-button — The pill's fill and the button's. The button reads white against the track in light; in dark it takes --background, because --surface is nearly the page itself there and would vanish into the track.
• --number-stepper-ink / --number-stepper-button-ink — --foreground for both.

Motion

Two animations, owned by different systems.

The press affordance is a motion animation on the icon span rather than a CSS transition — scale reaches it as an animate target and is never written as a static style value or as a Tailwind scale-* utility, both of which would be fighting motion for the same property. The timing is the settled asymmetric press: the press-in snaps (duration: 0) to scale: 0.82, and only the release eases back over 120ms on var(--ease-out). A symmetric press lags under the finger.

The value roll is the shared Odometer. At rest every wheel shows its exact integer digit; the wheels interpolate only while the spring is in flight, then ease back to a crisp integer the instant it settles. Leading non-significant wheels fade rather than pop, so the pill never changes width.

Everything else transitions colour only — the track, the buttons' fill and ink — which under the settled rule needs no opt-out at all: there is no movement in it to remove.

The reduced-motion opt-out therefore covers the scale and the roll, and covers both halves in JS, because a motion animation cannot be reached by a CSS media query: useReducedMotion handles prefers-reduced-motion: reduce, and a closest('[data-reduce-motion="true"]') probe handles the explicit hook, matching that selector's own reach of the element or any ancestor. A MutationObserver keeps a live toolbar toggle honest, and the probe runs in a layout effect so a reduced-motion reader never sees even one un-settled frame. Under either signal the scale pins to 1 and the odometer jumps rather than rolls, while the press still reads through its background change — gentler, not zero.

API Reference

NumberStepper

The root. Renders a React Aria NumberField and hands its parts the resolved layout and size. Also accepts every prop NumberField takes, including name, isRequired, isReadOnly, isInvalid, autoFocus, onBlur and validationBehavior.

NumberStepper.Group

The pill track holding the buttons and the value, and the box both modifiers land on. Also accepts every native <div> attribute.

NumberStepper.Label

The field's accessible name. Renders a real <label> React Aria ties to the input, so pressing it focuses the field. Also accepts every prop React Aria's Label takes.

NumberStepper.Value

The rolling number — the shared Odometer, reading the live value off React Aria's state so nothing is threaded through by hand. It does not replace Input: the two share a grid cell and swap when an edit starts, because an odometer is a stack of digit wheels and cannot live inside a text input. The input stays the accessible node and the hit target, and this part is aria-hidden, so nothing is announced twice. Must sit immediately before NumberStepper.Input.

NumberStepper.Input

The typeable field, and the accessible node. Also accepts every native <input> attribute.

NumberStepper.IncrementButton

The step-up button. React Aria supplies the press handler, the hold-to-repeat timer and the bound state through slot="increment" — there is no handler to pass. Renders the @blakeui/react Button, so it also accepts that component's props.

NumberStepper.DecrementButton

The step-down button, wired through slot="decrement". Same shape as the increment button, and it defaults to a minus glyph.

NumberStepper.Description

The supporting line under the control. React Aria's Text in the description slot, so it is tied to the input by aria-describedby rather than merely sitting near it.