Adjust a number
Use the stepper buttons when users need to increase or decrease a quantity.
Components
Quantity toggle
The quantity toggle component is used to increase or decrease an incremental value.
Set valid limits
Min, max, and step values help keep quantities within the allowed range.
Fit transactional flows
Use quantity toggles for tickets, bookings, orders, and similar counts.
1
Decrement action
2
Input value
3
Increment action
Range
Use the min and max attributes to constrain the value within an allowed range.
Sets a minimum and maximum so users cannot decrement below 0 or increment above 5.
Step
Use step to control how much the value changes each time the increment or decrement button is pressed.
The default. Each press of the increment or decrement button changes the value by one unit.
Hint text
Add hint text to clarify constraints such as a maximum allowed quantity.
Default. Use when the label alone is enough.
Read only
Use the read-only state when the value should be visible but not editable.
The default. Users can adjust the value with the increment and decrement buttons or by typing.
Disabled
Use the disabled state to prevent interaction when the field is not available in the current context.
The default. The quantity toggle is interactive and accepts input.
Validation feedback
When the value is invalid, surface inline feedback so users can correct the input.
No feedback styling. Use when the field has no validation requirements.
Design tokens used
Each row is a colour, spacing, or size value the component uses, and the right-most column tells you where in the component you'll see it.
sgds-gap-none—sgds-form-border-width-defaultWidth variessgds-form-border-radius-md—sgds-dimension-0—sgds-icon-size-md—When to use
- Use this component to collect or change a specific piece of information in a predictable way.
- Use it when the SGDS control matches the type of response users need to provide.
When not to use
- Do not use this component when another SGDS control would reduce effort or make the choice clearer.
- Do not ask for more information, options, or steps than users need at that point in the task.
Use quantity toggle for small, bounded counts
Quantity toggle is for items adjusted in single units, such as tickets or copies. For large numbers, use a number input.
Do not use quantity toggle for arbitrary numbers
Numbers without a count meaning, postcodes, IDs, amounts, do not belong in a quantity toggle.
Set min and max to reflect real limits
Use min and max to constrain the field to accepted values, and use hintText to tell users the maximum before they adjust it.
Do not use quantity toggle for large ranges
If users may need to enter values like 250 or 1,000, repeated incrementing becomes tedious. Use sgds-input type=number instead.
Pair with a label and explain the limit when needed
Always provide a label so users know what they count. Add hint text when the maximum is meaningful.
Do not use quantity toggle for precise values
Currency, measurements, percentages, or decimals need direct entry and clearer validation. Quantity toggle works best for whole-number counts.
Choose a step size that matches the use case
Increment by 1 for single-unit adjustments. Use a larger step only when typical adjustments are bigger.
Do not hide the allowed range
If there is a meaningful min or max, do not make users discover it by pressing the buttons. Show the limit in the label or hintText.
Surface invalid feedback inline
When the value falls outside the allowed range, set hasFeedback and invalid with a clear invalidFeedback.
Do not remove submitted values unintentionally
A disabled quantity toggle is excluded from form submission. Use readonly when the value should stay visible, unchanged, and still be submitted.
Built-in accessibility
- Quantity toggles combine an input with increase and decrease icon buttons.
- The input restricts unsupported keys and allows numeric editing keys.
Labels and content
- Use a label that describes what quantity is being changed.
- Set sensible minimum, maximum, and step values.
Focus and interaction
- Users should be able to reach the decrease button, input, and increase button in order.
- Validation feedback should explain any minimum or maximum constraint.
TabShift+TabNumber keysBackspace↓ Downor↑ Upor← Leftor→ RightHave suggestions or feedback?
Share them with us on Slack → #ask-sgds-v3
Found a bug or issue?
Report it on GitHub Issues → sgds/components/quantity-toggle