Numeric stepper
<forma-numeric-stepper>
Bounded numeric entry using the native number input and explicit constraints.
- Authoring tag
<forma-numeric-stepper>- Category
- Form inputs
- Behavior owner
- Native HTML
- Canonical source
patterns/numeric-stepper.html
Purpose
A numeric stepper collects a bounded number such as a count, quantity or duration. It is a native input type="number" with min, max and step, so the browser supplies typed entry, the spin buttons, ArrowUp/ArrowDown stepping and range/step validation. Forma lays the label, input and description out in a compact grid, limits the input to 10rem and uses tabular numerals so values line up.
Use when
- The value is a number with known bounds, such as seats, retries, a percentage or hours.
- Users may adjust by small increments or type the value directly.
- The number is short; a narrow input signals the expected size.
Avoid when
- The value is an identifier made of digits (account number, postcode, card number): use Text field with inputmode=numeric.
- An approximate value on a continuous scale is fine and the position is meaningful: use Slider, ideally with an adjacent numeric input.
- Users enter a lower and an upper bound: use Range entry.
- Several numbers must add up to a total: use Allocation.
Behavior to know
- The input is at most 10rem wide and uses tabular numerals.
- Constraints are native; out-of-range or off-step values fail validation on submit.
- State the bounds and unit in visible text, because spin buttons and constraints are not visible or announced consistently.
Basic example
The smallest correct markup: the canonical pattern from patterns/numeric-stepper.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal numeric stepper
Rendered from the canonical pattern file.
<forma-numeric-stepper class="forma-component-tag">
<label class="forma-numeric-stepper">
<span class="forma-numeric-stepper__label">Target deployments per week</span>
<input type="number" name="deployments-per-week" min="0" max="50" step="1" inputmode="numeric" required>
<span class="forma-field__description">Enter a whole number from 0 through 50.</span>
</label>
</forma-numeric-stepper>
Click or tap the code once to select all of it, then copy.
Examples
Hours in half-hour steps
A decimal quantity with a unit. step=0.5 lets ArrowUp/ArrowDown move by half an hour, and inputmode=decimal shows a keypad with a decimal separator on phones. The label uses for/id and the description sits outside the label so it is announced as a description, not as part of the name.
<forma-numeric-stepper class="forma-component-tag">
<div class="forma-numeric-stepper">
<label class="forma-numeric-stepper__label" for="numeric-stepper-hours-input">Time spent (hours)</label>
<input id="numeric-stepper-hours-input" type="number" name="hours-spent" min="0" max="24" step="0.5" value="1.5" inputmode="decimal" aria-describedby="numeric-stepper-hours-description">
<span class="forma-field__description" id="numeric-stepper-hours-description">0 to 24, in steps of 0.5.</span>
</div>
</forma-numeric-stepper>
Click or tap the code once to select all of it, then copy.
Value above the maximum
The user typed 60 for a limit whose maximum is 50. The application marked the input invalid after the native check failed and linked a message stating the allowed range; the typed value is kept.
<forma-numeric-stepper class="forma-component-tag">
<div class="forma-numeric-stepper">
<label class="forma-numeric-stepper__label" for="numeric-stepper-retries-input">Maximum retries</label>
<input id="numeric-stepper-retries-input" type="number" name="max-retries" min="0" max="50" step="1" value="60" inputmode="numeric" required aria-invalid="true" aria-describedby="numeric-stepper-retries-description numeric-stepper-retries-error">
<span class="forma-field__description" id="numeric-stepper-retries-description">Whole number from 0 through 50.</span>
<p class="forma-validation-message" id="numeric-stepper-retries-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Enter 50 or fewer retries.
</p>
</div>
</forma-numeric-stepper>
Click or tap the code once to select all of it, then copy.
Fixed by contract
A seat count set by the contract. readonly keeps the value focusable and submitted while the description explains where to change it.
<forma-numeric-stepper class="forma-component-tag">
<div class="forma-numeric-stepper">
<label class="forma-numeric-stepper__label" for="numeric-stepper-seats-input">Licensed seats</label>
<input id="numeric-stepper-seats-input" type="number" name="licensed-seats" min="1" max="1000" value="250" readonly aria-describedby="numeric-stepper-seats-description">
<span class="forma-field__description" id="numeric-stepper-seats-description">Set by your contract. Contact your account manager to change it.</span>
</div>
</forma-numeric-stepper>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile order quantities
Two quantities at phone width in the canonical label-wrapped structure. The inputs stay compact while labels and descriptions wrap.
What changes at narrow widths
- Inputs stay at most 10rem wide at every width, so the narrow field keeps signalling a short number.
- Labels and descriptions wrap onto several lines; nothing scrolls horizontally at 320px.
- inputmode=numeric shows a digit keypad on phones; many mobile browsers hide the spin buttons, so typed entry is the main path.
- Each input keeps a 44px minimum height for touch.
- Orientation changes only reflow the text.
<forma-numeric-stepper class="forma-component-tag">
<div class="forma-stack">
<label class="forma-numeric-stepper">
<span class="forma-numeric-stepper__label">Replacement badges to print</span>
<input type="number" name="badge-quantity" min="1" max="20" step="1" value="1" inputmode="numeric">
</label>
<label class="forma-numeric-stepper">
<span class="forma-numeric-stepper__label">Visitor passes for the event day</span>
<input type="number" name="visitor-passes" min="0" max="100" step="5" value="10" inputmode="numeric">
</label>
</div>
</forma-numeric-stepper>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
type | input | number | — | Required. Native number entry and stepping. |
min | input | number | — | Lower bound; stepping stops here and lower typed values are invalid. |
max | input | number | — | Upper bound. |
step | input | number | any | 1 | Increment for ArrowUp/ArrowDown and allowed granularity; off-step values are invalid unless step=any. |
value | input | number | empty | Initial value. |
inputmode | input | numeric | decimal | from type | Chooses a digit or decimal keypad on touch devices. |
name | input | string | — | Form field name. |
required | input | boolean | absent | Blocks submission while empty. |
readonly | input | boolean | absent | Focusable and submitted but not editable or steppable. |
for | label.forma-numeric-stepper__label | id of the input | — | Use when the root is not the label, so the description can stay out of the accessible name. |
aria-describedby | input | id list | — | Links the range description and any validation message. |
aria-invalid | input | true | absent | Set by the application while a validation message is shown. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-numeric-stepper | Block class | — | Root grid (label element or wrapper) stacking label, input and description with a 0.5rem gap. Constrains a descendant number input to 10rem with tabular numerals. |
.forma-numeric-stepper__label | Element class | — | Visible label text in bold. |
| Keys | Result |
|---|---|
| ArrowUp / ArrowDown | Increments or decrements by step, clamped to min and max (native). |
| Digits, minus, decimal separator | Types the value directly. |
| Tab / Shift+Tab | Moves focus to and from the input. |
| Event | Description |
|---|---|
input / change / invalid | Native events. Forma adds none. |
Form behavior
A native number input: submits the numeric string under name, validates min, max, step and required, and resets to its initial value.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Default | value within bounds | Compact bordered input with tabular numerals. |
| Focus | :focus-visible | Foundation two-tone focus ring. |
| Invalid | aria-invalid="true" plus a linked .forma-validation-message | Error line with a non-color mark. Native :invalid (out of range or off step) is not restyled by Forma. |
| Read-only | readonly attribute | Native behavior with no distinct styling; explain it in the description. |
| Disabled | disabled attribute | Skipped by focus and not submitted; Forma adds no dimmed style. |
Accessibility
Forma provides
- Keeps the native number input, so stepping keys, spin buttons and range validation come from the platform.
- The input keeps a 44px minimum height and the shared focus ring.
- Borders map to CanvasText in forced-colors mode.
Your application supplies
- State the range, step and unit in visible text.
- In the canonical label-wrapped structure the description sits inside the label and becomes part of the accessible name; keep it short, or use a wrapper with for/id and aria-describedby as in the scenario examples.
- Explain invalid values with a linked Validation message that names the allowed range.
Responsive behavior
- The number input is capped at 10rem and otherwise fills its column; the label and description wrap at any width.
- No breakpoints of its own.
- Many mobile browsers hide spin buttons; typed entry with a numeric keypad remains available.
Motion
- No animation: the stepper does not transition. Values change immediately.
Usage guidance
Do
- Choose a step that matches how people think about the value (1 for counts, 0.5 for hours, 5 for percentages).
- Put the unit in the label or description.
Avoid
- type=number for values with leading zeros or digit groups, such as codes and phone numbers.
- Silently clamping a typed value; tell the user what changed.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.