组件

Stepper

A number you can nudge: minus, the value, plus. One hand-drawn box with a tick before each button, the number in script, buttons that repeat while you hold them, arrow keys and PageUp / PageDown for the keyboard, and a rattle of the box when there is nowhere left to go. The value is a real text input, so it types, pastes and submits with a form.

安装

terminal
npx shadcn@latest add @wobko/stepper

第一次使用?先把 registry 加进 components.json。 如何安装

示例

Quantity

Press the plus, hold it to run, or type. Arrow keys step, Shift or PageUp / PageDown jump ten, Home and End go to the ends. At 10 the plus has nothing left and rattles the box.

Steps, decimals and units

A step of 0.5 on a price (no float drift, shown with two places), a temperature in whole degrees with the wheel opt-in (click into it and scroll), and a value that snaps to multiples of five.

Cart lines with tally marks

The stepper in a cart: each line counts its quantity in tally marks next to the number, the total follows, and a line at zero says so. The tally is decoration; the number is the truth.

In a form

name puts the number in FormData; required refuses an empty field (a blank is put back); Reset returns an uncontrolled stepper to its default. The third one is invalid, the fourth disabled.

API 参考

Stepper

The control (`role="group"`, the drawn box). Without children it is `StepperDecrement`, `StepperInput` and `StepperIncrement`; compose your own to add a `StepperTally` or other parts. Uncontrolled (`defaultValue`) or controlled (`value` + `onValueChange`; `value={undefined}` is a controlled, empty field). The value is a number, or `undefined` while the field is empty (NaN and Infinity count as empty, never the text "NaN").

属性类型默认值说明
value / defaultValue / onValueChangenumber | undefined-The value. `onValueChange` fires when a button, key, wheel step or typed number (read on Enter or blur) changes it.
min / maxnumber-Bounds. Steps and typed numbers are clamped; a button with nothing left is `aria-disabled` (not `disabled`, so focus is not lost) and rattles the box when pressed.
stepnumber1The size of a button press or an arrow key. Zero, negative or not a number falls back to 1.
largeStepnumber10 x stepShift + arrows and PageUp / PageDown.
snapbooleanfalseRound typed and stepped values to multiples of `step` counted from `min` (or 0).
precisionnumber-Decimal places to show and round to. Default: the most places the step, the minimum and the current value have, so 0.1 steps do not drift.
format / parse(n: number) => string / (text: string) => number | undefined-How the number is shown and read back: currency, units. The default reader takes a dot or a comma as the point, both together ("1,234.5", "1.234,5" are 1234.5), a repeated separator as thousands ("1,234,567"), and Eastern Arabic and Persian digits. A lone "1,234" is 1.234: with one separator there is no telling a decimal comma from a thousands comma, so pass `parse` for your locale. A `parse` that answers NaN puts the last good value back.
wheelbooleanfalseThe mouse wheel steps the number while it has focus (and stops the page scrolling). Off by default: a wheel that changes values under a scrolling page is a trap.
id / name / form / required-Go to the number's input: `id` for a Label, `name` and `form` for forms (with a `format`, a hidden input carries the plain number and the shown text is only the display), `required` forbids an empty field.
aria-label / aria-labelledby / aria-describedbystring-Names for the number (the spinbutton), not for the group.
disabled / readOnly / invalidboolean-Dashed pencil on a wash / a value that is shown but not changed / the red pencil box.
seedstring | number-Pins the hand: the same seed always draws the same box.

StepperTally

The value as tally marks (four strokes and a slash to a group), a companion for a quantity you count on your fingers. Decorative (`aria-hidden`).

属性类型默认值说明
maxnumber20How many marks to draw at most.

无障碍

  • The number is a text input with `role="spinbutton"` and `aria-valuenow / valuemin / valuemax / valuetext` (the APG pattern), so screen readers announce it as a number field; ArrowUp / ArrowDown, PageUp / PageDown, Home and End work as the pattern says. Give it a name (a Label with `htmlFor`, or `aria-label`).
  • The buttons are not in the tab order (as in the APG spinbutton: the input takes the keyboard) but they are real buttons, so a pointer, a switch and a screen reader's activate (a click with no pointer) step once each. Name them for what they change.
  • A button with nothing left is `aria-disabled`, not `disabled`; pressing it rattles the box (a visual cue that goes with the state, not instead of it) and the number's `aria-valuenow` stays.
  • Holding a button repeats; releasing (or leaving, or blur) stops, and so does reaching a bound. No motion depends on it: reduced motion turns the number's tick and the box's rattle off.
  • The wheel is opt-in, and only acts while the number has focus.
  • Hit areas are the whole cell (36 px, 32 compact, 28 calm), the drawn ticks and box are `aria-hidden`; in Windows high contrast the box gets a real border.

源码

CLI 会复制进你项目的文件。

正在加载源码