CatalystQuantity Pickerv0.2.2Documentation Under Review
An accessible increment/decrement control built with CVA variants, four size options, danger state, and full keyboard support.
Prefer AI-assisted development?
Catalyst Quantity Picker is a compound component for selecting numeric values — increment, decrement, min/max constraints, danger thresholds, and four size variants included out of the box.
Installation
npm install @pmi/catalyst-quantity-pickerimport {
QuantityPickerRoot,
QuantityPickerTrigger,
QuantityPickerValue,
} from '@pmi/catalyst-quantity-picker';Sizes
Four sizes are available via the size prop on QuantityPickerRoot.
Common Patterns
Danger State
Use danger on QuantityPickerTrigger and QuantityPickerValue to highlight critical quantities or warning thresholds.
Disabled State
Disable individual triggers when the value has reached its boundary, or pass disabled to both triggers to block all interaction.
API Reference
Quantity Picker is a compound component. The sections below cover the props specific to each part.
QuantityPickerRoot
The flex container that provides the size context to all child parts via data-size.
Prop
Type
QuantityPickerTrigger
The increment or decrement button. Always provide a descriptive aria-label — the trigger renders an icon only.
Prop
Type
QuantityPickerValue
Displays the current numeric value between the two triggers.
Prop
Type
Accessibility
Quantity Picker is designed to meet WCAG 2.2 AA standards.
Keyboard Interactions
| Key | Action |
|---|---|
Tab | Moves focus between the decrement and increment buttons |
Shift + Tab | Moves focus in reverse |
Enter | Activates the focused trigger button |
Space | Activates the focused trigger button |
ARIA
- Each
QuantityPickerTriggeris a<button>— always supplyaria-label(e.g."increase quantity","decrease quantity") because the buttons contain icons only (WCAG 2.2 SC 1.1.1). - Set
disabledon a trigger when its boundary is reached so the button is correctly reported as unavailable to assistive technology (WCAG 2.2 SC 4.1.2). - Consider adding an
aria-live="polite"region adjacent to the picker to announce value changes to screen readers. - All interactive states (focus, disabled) meet the WCAG 2.2 AA minimum contrast of 3:1 for non-text elements (SC 1.4.11).
Choosing the Right Component
Use Quantity Picker when users need to select a bounded integer value one step at a time. Reach for a different primitive when:
| If you need… | Use instead |
|---|---|
| A continuous range with a draggable handle | Slider |
| Free-form numeric text entry | Text Field |
| A multi-step workflow progress control | Stepper |
Related
Map
Interactive map component for visualizing geographic data with markers, popovers, and zoom controls. Built on react-simple-maps with customizable geographies and Catalyst design tokens.
Radio Cards
A deprecated radio group component with card-style visual presentation. Use RadioGroup component for new implementations with better accessibility and simpler API.