Skip to content

SpinButton

C-37 · Components · Editor (Office)

All elements · SpinButton on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for SpinButton.

SpinButton

C-37 OfficeWCAG 2.2 AA · Passed

A numeric field with ▲▼ steps and a unit: role="spinbutton" with aria-valuetext ("1.27 centimeters"). ↑/↓ step, PageUp/PageDown take a large step.

Axis / element Values
__input · __unit · __steps · __up · __down parts
data-size sm (default, ribbon) · md (dialogs)
Units

Guidance

When to use

  • Use it for a numeric value with a unit in the office editors, such as indent, spacing, scale or column width.
  • Use data-size="sm" (the default) in the ribbon and data-size="md" in dialogs.
  • Use it when users both type exact values and nudge them in steps.
  • Show the unit in __unit and say it in full in aria-valuetext, such as "1.27 centimeters".

When to consider something else

  • When the exact number matters less than a quick visual adjustment, such as zoom or transparency, use a Slider. See Slider.
  • For a number in a record form outside the editors, use a Text field with numeric input. See TextField.
  • When the value comes from a short fixed list, use a Select. See Select.

Usability

Do
  • Set aria-valuemin and aria-valuemax to the real limits and clamp typed values to them.
  • Accept typed values in the shown unit, and keep aria-valuenow and aria-valuetext in sync.
  • Name the step buttons after the field, such as "Increase indent left".
  • Use Fluent Regular chevrons for the steps inside .qf-office (README, Icons).
Don’t
  • Don't hide the unit, or put it only in the placeholder.
  • Don't put the step buttons in the tab order; the keyboard steps from the field.
  • Don't reject an out-of-range entry silently; clamp it or show an error the user can read.

Accessibility

Keyboard

SpinButton keyboard
Keys Action
Tab Moves focus to the field; the step buttons are skipped.
Arrow Up / Arrow Down The binding must increase or decrease the value by one step.
Page Up / Page Down The binding must increase or decrease the value by a large step.
Home / End The binding should set the minimum or maximum value when both are defined.
Arrow Left / Arrow Right Move the caret in the field; the ribbon toolbar does not take them from a text input.
Enter The binding must commit a typed value.

Roles and names

  • __input has role="spinbutton", an aria-label, aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext with the full unit word.
  • __unit is aria-hidden, because aria-valuetext already says the unit.
  • __up and __down are buttons with tabindex="-1" and names such as "Increase scale".

Focus

  • The whole control shows the focus ring through :focus-within while the field has focus.
  • Clicking a step button must leave focus in the field.

Other requirements

  • The step buttons are 1rem wide and half the field height, below 2.5.8's 24px; typing and the arrow keys are the equivalent, so the field itself must stay at least 24px high.
  • The sm field is 1.5rem (24px) high and md is 2rem.
  • In forced colors the border becomes CanvasText.
  • If a value fails validation, describe the error in text and link it with aria-describedby (3.3.1).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

SpinButton test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (6 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (3 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- spin-button --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

SpinButton package
Source css/classic/components/pickers.css
Specimens also use Box · Card · Chip · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg · sprites/office-icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes