Button Group
Last Updated: May 22, 2026Button Groups give users an array of options they can toggle on or between in a given UI.
Source CodeAnatomy
link- 1Container
- 2Buttons
- 3Divider
Variants
linkSingle-select (Radio)
Restricts users to one active option within the group. Ideal for exclusivity, such as billing cycles (Monthly, Quarterly, Annual).
Multi-select (Checkbox)
Allows users to enable several options at once. Commonly used for independent preferences such as notification settings (Email, SMS, Push).
Sizes
linkButton groups support 2 sizes: S and M (buttons inherit size from the group).
Usage Guidelines
linkWhen to use
- •To present a small set of exclusive options (single-select).
- •To allow selection of multiple related options (multi-select).
- •When button-style interaction is preferred over traditional form inputs.
When not to use
- •Large option sets → use Select or a searchable Combobox.
- •Options requiring long text or supporting content → use form-based components.
Use meaningful, scannable labels that fit on a single line.
Don't use overly long or multiline labels — they break the segmented layout.
Behaviors
linkSelection vs Action
- •The active option is rendered with the primary variant to communicate selection.
- •onClick fires a callback; the consumer updates the selected state manually (controlled component).
Modifiers
- •The primary variant on a child visually marks it as the active / selected option.
- •disabled on a child button makes it visually inactive and removes interactivity while maintaining layout.
Sizing
- •Set size on the ButtonGroup and it cascades to every child Button.
- •Individual children cannot override the group size — this keeps the segmented control uniform.
Content Guidelines
linkClarity & Accessibility
- •Provide clear, descriptive labels (e.g., "Monthly", "Quarterly").
- •Avoid ambiguous labels (e.g., "Option 1", "Select").
- •Always prefer visible text — icon-only toggles should be avoided for clarity.
Consistency
- •Use sentence case ("Monthly billing").
- •Maintain consistent phrasing across all options in a group.
- •Align terminology with domain-specific language (e.g., "Equity", "Debt").
Placement
- •Group options logically by context (e.g., notification channels, billing frequencies).
- •Use single-select when exactly one option must be chosen.
- •Use multi-select when multiple independent options are valid.
Accessibility
linkText & Labels
- •Always include visible text on each button.
- •Use aria-label on the ButtonGroup for additional clarity when the purpose isn't obvious from context.
ARIA attributes
- •aria-pressed → communicates the selected state of a toggle option.
- •aria-label → announces the group's purpose.
- •role is derived from the underlying button elements.
Keyboard Support
- •Tab → move focus into the group.
- •Space / Enter → toggle the focused option.
WCAG Compliance Standards
FAQs
linkCan I mix single-select and multi-select in the same ButtonGroup?
No. Mixing selection modes creates inconsistent interaction patterns. Pick one behavior per group.
How do I set a default option?
Initialize your state with the desired option's key so it renders with the primary variant on first paint.
Is this suitable for long lists?
No. Use Select or a searchable Combobox for longer or dynamic lists.