Form inputs

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.

Canonical

Minimal numeric stepper

Rendered from the canonical pattern file.

HTML · Minimal numeric stepper Raw HTML for HTML · Minimal numeric stepper
<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

Scenario

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.

0 to 24, in steps of 0.5.
HTML · Hours in half-hour steps Raw HTML for HTML · Hours in half-hour steps
<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.

Scenario

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.

Whole number from 0 through 50.

Enter 50 or fewer retries.

HTML · Value above the maximum Raw HTML for HTML · Value above the maximum
<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.

Scenario

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.

Set by your contract. Contact your account manager to change it.
HTML · Fixed by contract Raw HTML for HTML · Fixed by contract
<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 example

Mobile order quantities

Two quantities at phone width in the canonical label-wrapped structure. The inputs stay compact while labels and descriptions wrap.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.
HTML · Mobile order quantities Raw HTML for HTML · Mobile order quantities
<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.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

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.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
typeinputnumber—Required. Native number entry and stepping.
mininputnumber—Lower bound; stepping stops here and lower typed values are invalid.
maxinputnumber—Upper bound.
stepinputnumber | any1Increment for ArrowUp/ArrowDown and allowed granularity; off-step values are invalid unless step=any.
valueinputnumberemptyInitial value.
inputmodeinputnumeric | decimalfrom typeChooses a digit or decimal keypad on touch devices.
nameinputstring—Form field name.
requiredinputbooleanabsentBlocks submission while empty.
readonlyinputbooleanabsentFocusable and submitted but not editable or steppable.
forlabel.forma-numeric-stepper__labelid of the input—Use when the root is not the label, so the description can stay out of the accessible name.
aria-describedbyinputid list—Links the range description and any validation message.
aria-invalidinputtrueabsentSet by the application while a validation message is shown.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-numeric-stepperBlock 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__labelElement class—Visible label text in bold.
Keyboard interaction
KeysResult
ArrowUp / ArrowDownIncrements or decrements by step, clamped to min and max (native).
Digits, minus, decimal separatorTypes the value directly.
Tab / Shift+TabMoves focus to and from the input.
Events
EventDescription
input / change / invalidNative 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

Numeric stepper states
StateHow it is expressedPresentation
Defaultvalue within boundsCompact bordered input with tabular numerals.
Focus:focus-visibleFoundation two-tone focus ring.
Invalidaria-invalid="true" plus a linked .forma-validation-messageError line with a non-color mark. Native :invalid (out of range or off step) is not restyled by Forma.
Read-onlyreadonly attributeNative behavior with no distinct styling; explain it in the description.
Disableddisabled attributeSkipped 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.