Number Stepper

Anatomy

import {NumberStepper} from '@staffbase/design';

<NumberStepper.Root>
  <NumberStepper.Decrement />
  <NumberStepper.Input />
  <NumberStepper.Increment />
</NumberStepper.Root>

API reference

Root

Increment

Decrement

Input

When to use

• For adjusting a small numeric quantity where users typically move only a few steps, such as 1–10 slides in a slideshow.
• When the value has a defined minimum and maximum that the control can enforce.
• When stepping up and down is the primary interaction and typing an exact number is the exception.
• When the value changes in fixed units, such as a duration in steps of 5 seconds.

When not to use

• Don’t use a Number Stepper for values that commonly exceed 20, because stepping there costs too many clicks — use Text Field instead.
• Don’t use a Number Stepper for an open-ended number with no defined minimum and maximum — use Text Field instead.
• Don’t use a Number Stepper for input that isn’t a number, such as a code or a formatted date — use Text Field instead.
• Don’t use a Number Stepper to pick one of a few fixed values, such as 5, 10, or 25 — use Select or Segmented Control instead.
• Don’t use a Number Stepper for an on/off setting — use Switch instead.
• Don’t use a Number Stepper on its own without a label and a stated range — wrap it in Field instead.

How to use

Structure

• Compose the stepper as NumberStepper.Root containing Decrement, Input, and Increment in that order — all three parts are required.
• Wrap every stepper in a Field.Root with a Field.Label so the value always has a visible name.
• State the range and the unit in Field.Description, such as 1–10 Slides.
• Set defaultValue to the most common value, and keep it inside the min–max range.

Range & steps

• Always set min and max so the control enforces its bounds.
• Keep the whole range within roughly 20 steps; if reaching the maximum takes more steps than that, raise the step size or switch to a Text Field.
• Keep the decrement and increment buttons visible in their disabled state at the bounds instead of hiding them, so the limit stays discoverable.
• Use step when only certain values are valid, such as step={5} for 5, 10, 15.
• Add snapOnStep when a custom step is set, so a typed value snaps to the nearest valid step.
• Only allow negative values when a negative number is meaningful, such as an offset; otherwise set min={0}.

Validation

• State the allowed range in the description up front, not only in an error message.
• When a typed value falls outside the range, mark the field invalid and show a Field.Error that names the range, such as Input a number between 1–10.
• Reuse the exact range wording from the description in the error message.
• Mark a required stepper with requiredLabel on Field.Label and aria-required on NumberStepper.Input.

Layout & sizing

• Widen only the input when longer values or units need more room, and keep the whole control at 240px or less.
• Don’t stretch the stepper to 100% width, because the buttons drift away from the value and increase pointer travel.
• Keep the three parts joined on a single line so they read as one control.

Accessibility

• Always provide a visible Field.Label; placeholder text is not a label.
• Keep the default minus and plus icons, which carry the built-in Decrease and Increase accessible names.
• Support direct typing in the input — stepping must never be the only way to reach a value.
• Arrow Up and Arrow Down change the value by one step, and holding Shift applies the larger step.
• Render the description and the error through Field.Description and Field.Error so they are linked to the input for screen readers.
• Don’t rely on the red border alone to signal an invalid value — always show error text.

Content & UX copy

• Use Title Case for the field label, such as Posts per Slideshow.
• Use an en dash for a range of positive values, such as 1–10.
• Write a range that includes a negative bound as between −5 and 5, so the minus sign isn’t mistaken for the dash.
• Name the unit once in the description, such as Seconds per Slide, and don’t repeat it in the label.
• Keep the description to one short phrase that states the range and the unit.