QuantityStepper

Tier: client

ImportCopy Anchor Link

import { QuantityStepper } from '@nizivo/react/quantity-stepper';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/input.css
import '@nizivo/react/css/quantity-stepper.css';

Static or interactiveCopy Anchor Link

Client. It always ships its client leaf, which reads its Field through FieldScope, so a page with a QuantityStepper also loads FieldScope. The server HTML is a native number input that works before hydration, arrow keys included; the buttons work once the page has hydrated. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

The buttonsCopy Anchor Link

The minus and plus buttons are for the pointer. They are out of the tab order, a press never moves focus, and each is named for a screen reader's pointer modes: "Decrease quantity" and "Increase quantity" (labels.decrement and labels.increment), with aria-controls pointing at the input. A keyboard user steps with the arrow keys, which a screen reader announces as the input's value. Each button is disabled at its end of the range, and both while the input is read-only or disabled.

A press steps the input as an arrow key would (stepUp() and stepDown(); an empty input starts at min) and fires the native input and change events, so onChange, a form's own listeners and a Field see an ordinary edit. decrementIcon and incrementIcon replace the internal minus and plus glyphs.

ValuesCopy Anchor Link

min is 0 and step is 1 unless set; max has no default. value and defaultValue are numbers, and value={null} is an empty input. onValueChange(value, details) reports every change, typed or pressed: the number, or null while the input is empty, with details.reason 'increment', 'decrement' or 'input'.

Quantities are whole numbers. A typed fraction fails the input's step, so inside a Field messages.stepMismatch names the problem; a decimal amount, such as a price, is a NumberField's job.

WidthCopy Anchor Link

The input is three characters wide, enough for 999. --nz-quantity-stepper-input-width sets another width, for example 5ch.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { QuantityStepper } from '@nizivo/react/quantity-stepper';

export function QuantityStepperExample(): JSX.Element {
  return (
    <Field name="quantity" label="Quantity" description="Up to 10 per order.">
      <QuantityStepper min={1} max={10} defaultValue={1} />
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { QuantityStepper } from '@nizivo/react/quantity-stepper';

export function QuantityStepperStatesExample(): JSX.Element {
  return (
    <div style={{ display: 'grid', gap: 16, justifyItems: 'start' }}>
      <QuantityStepper size="sm" aria-label="Small" defaultValue={2} />
      <QuantityStepper aria-label="Medium" defaultValue={2} />
      <QuantityStepper size="lg" aria-label="Large" defaultValue={2} />
      <Field label="Quantity" description="Only 3 left in stock.">
        <QuantityStepper min={1} max={3} defaultValue={3} />
      </Field>
      <QuantityStepper aria-label="Read-only" defaultValue={4} readOnly />
      <Field label="Quantity" disabled>
        <QuantityStepper defaultValue={1} />
      </Field>
    </div>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

QuantityStepperLabels type

import type { QuantityStepperLabels } from '@nizivo/react/quantity-stepper'

QuantityStepper's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
decrementrequired	string	'Decrease quantity'	The minus button's name.
incrementrequired	string	'Increase quantity'	The plus button's name.

QuantityStepperProps type

import type { QuantityStepperProps } from '@nizivo/react/quantity-stepper'

The props of QuantityStepper, listed above.

QuantityStepperState type

import type { QuantityStepperState } from '@nizivo/react/quantity-stepper'

The render state of QuantityStepper, listed above.

QuantityStepperValueReason type

import type { QuantityStepperValueReason } from '@nizivo/react/quantity-stepper'

'decrement' / 'increment': a button was pressed. 'input': typed, or an arrow key.

type QuantityStepperValueReason = "decrement" | "increment" | "input"

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-input, .nz-quantity-stepper, .nz-quantity-stepper-button, .nz-quantity-stepper-control, .nz-quantity-stepper-icon.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• quantity-stepper: draws the outline when the field inside it has focus.

KeyboardCopy Anchor Link

Source: a native <input type="number"> between two <button type="button" tabIndex={-1}> (quantity-stepper.client.tsx). The browser lane (test/browser/quantity-stepper.spec.tsx) checks the buttons by pointer, the arrow keys, Tab reaching only the input, the events a press fires, controlled use and a Field's message for a typed fraction.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7367:377
• Ghost masters: none