angular / angular/components

feat(aria/spinbutton): Add spinbutton primitive for value selection within discrete ranges

Open
#32,664 4 comments 5 reactions 1 assignee Claimed by @ok7sai View on GitHub
area: cdk/a11y feature P3
Dominant language
TypeScript
Stars
25k
Forks
6.8k
Avg merge
1d 8h
Merged PRs (30d)
91

Description

### Feature Description

Angular Aria currently lacks a spinbutton primitive.
The [APG Spinbutton Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) defines it as an input widget that restricts its value to a set or range of discrete values.

### Keyboard Interaction (per APG)
| Key | Function |
|-----|----------|
| Up Arrow | Increases the value |
| Down Arrow | Decreases the value |
| Home | Sets value to minimum (if defined) |
| End | Sets value to maximum (if defined) |
| Page Up | Increases value by larger step (optional) |
| Page Down | Decreases value by larger step (optional) |

### Required ARIA Attributes
- `role="spinbutton"` on the focusable element
- `aria-valuenow` - Current value
- `aria-valuemin` / `aria-valuemax` - Min/max allowed values
- `aria-valuetext` - User-friendly string (e.g., "Monday" instead of "1")
- `aria-labelledby` or `aria-label` - Accessible name
- `aria-invalid="true"` - When value is outside allowed range

### References

**APG Specification**
- [Spinbutton Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/)
- [Quantity Spin Button
Example](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/examples/quantity-spinbutton/)
- [Toolbar Example](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/examples/toolbar/) (includes font size
spinbutton)

**React Aria Prior Art**

React Aria uses spinbuttons internally for date/time segment navigation:
- [TimeField](https://react-spectrum.adobe.com/react-aria/TimeField.html)
- [DateField](https://react-spectrum.adobe.com/react-aria/DateField.html)
- [DateRangePicker](https://react-spectrum.adobe.com/react-aria/DateRangePicker.html)

### Implementation

PR: https://github.com/angular/components/pull/32663

### Use Case

1. **Quantity Selection** - Hotel booking, shopping carts, product pages
2. **Time Input** - Time pickers with hours, minutes, seconds segments
3. **Date Picker Components** - Date range selectors using spinbuttons for date segments
4. **Toolbar Controls** - Font size and property controls in text editors
5. **Numeric Input with Constraints** - Any value selection within a min/max range

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.