Spinbutton / numeric stepper

Problem Context

• The value is a real number or count that can be incremented or decremented.
• Most changes are small, such as adding one guest, copy, item, seat, day, night, or minute.
• The product knows the lower bound, upper bound, step size, unit, and default.
• Users may need to type the number directly instead of repeatedly pressing buttons.
• Some numeric-looking values must remain strings and should not become spinbuttons.

Selection Rules

• Choose a spinbutton for one bounded numeric value that changes in predictable increments.
• Use it when a default such as 0 or 1 is meaningful and most users make only a few adjustments.
• Provide direct typing whenever the range has more than a handful of steps or users may already know the exact value.
• Use slider when relative position across a wider range matters more than repeated count changes.
• Use range slider when users set both lower and upper boundaries.
• Use text input for arbitrary numbers, pasted values, precise decimals, financial amounts, or numeric-looking identifiers.
• Use select, radio, or segmented controls for named options that should be compared as labels.
• Avoid spinbuttons for account numbers, payment cards, verification codes, postal codes, phone numbers, dates, and other strings that merely contain digits.

Required States

• Initial state with visible label, default value, unit, min, max, and step.
• Focused value field state.
• Increment and decrement button hover, focus, pressed, and disabled-at-bound states.
• Direct typed valid value state.
• Required empty value state.
• Below-minimum and above-maximum repair or error states.
• Non-step value repair state when the typed value falls between allowed increments.
• Large-step keyboard state when Page Up and Page Down are supported.
• Disabled dependency state with explanation.
• Read-only review state that remains readable and programmatically exposed.

Interaction Contract

• Increment and decrement controls change the value by the declared step and stop at the lower and upper bounds.
• The editable field accepts direct numeric entry and preserves standard text-editing behavior.
• Up Arrow and Down Arrow move by one step; Home and End move to known bounds when supported; Page Up and Page Down move by a documented larger step when present.
• Min, max, step, value, unit, and invalid state stay synchronized between visual controls, programmatic state, and submitted value.
• Out-of-range, empty, and non-step values are rejected or repaired with visible feedback before submission.
• Disabled and read-only states explain whether the quantity is unavailable or only reviewable.

Implementation Checklist

• Confirm the value is incrementable, not a numeric string identifier.
• Define min, max, step, default, unit, decimal precision, large-step behavior, and whether immediate commit or form submit applies.
• Use a native number input or implement spinbutton roles and value attributes only when native behavior is insufficient.
• Label the field and give plus and minus controls names that include the affected quantity.
• Keep direct text entry, paste, selection, undo, and keyboard editing available unless the target platform explicitly supports a button-only stepper.
• Disable the minus button at the minimum and the plus button at the maximum without disabling the whole field unnecessarily.
• Validate on blur or submit, clamp only with explanation, and run the same checks server-side.
• Test keyboard, pointer, touch, screen reader, high zoom, forced colors, locale decimal entry, disabled, read-only, and mobile numeric keyboard behavior.

Common Generated-UI Mistakes

• Using a spinbutton for numeric-looking identifiers or codes.
• Using one-step buttons for a large range without direct typing or larger-step movement.
• Omitting the label, unit, min, max, default, or current value.
• Providing plus and minus buttons with accessible names that do not identify the quantity.
• Silently rounding decimals or repairing invalid values without telling the user.
• Disabling the whole control when only one direction is unavailable at a bound.
• Using a workflow stepper or progress indicator when the task needs a numeric value control.

Critique Questions

• Is the value actually incrementable, or is it a string made of digits?
• Will most users change the default by only a few steps?
• Can users type the exact value, paste, undo, and recover from errors?
• Are the min, max, step, unit, current value, and disabled-bound states visible and programmatic?
• Would a slider, range slider, text input, select, or workflow step navigation communicate the job more clearly?