This task defines the minimum viable product (MVP) of the ToggleButtonGroup component.
Scope
Design spec
Anatomy
A ToggleButtonGroup consists of 2 or more buttons displayed horizontally adjacent to each other.
The initial component has two variants:
- The "single-select toggles" variant: a group of ToggleButtons, where only one can be selected (toggled on) at one time (similar to a group of radio buttons)
- The "multiselect toggles" variant: a group of ToggleButtons, where multiple buttons can be selected (toggled on) at any one time (similar to a group of checkboxes)
The design specifies that icons should be used consistently across buttons: buttons in an ActionButtonGroup should all be one of the following:
- Text only
- Icon + text
- Icon-only
If feasible, we should inspect the data or slot contents to see if this specification is met and, if not, emit a warning to the console explaining that icon usage should be consistent across buttons.
Style
The initial component will present the following visual features:
- Buttons are displayed next to each other (horizontally)
- The borders of adjacent buttons overlap
- The first and last buttons have rounded corners on the outside; all the other corners are sharp (not rounded)
- Disabled behavior:
- The ToggleButtonGroup as a whole can be disabled, in which case all of its child buttons are disabled
- Any button within a ToggleButtonGroup can be individually disabled
Interaction
The initial component will follow these interaction specifications:
For the "single-select toggles" variant:
- Only one button can be selected (toggled on) at any time. When a button is clicked, it becomes selected, and if any other button was already selected, that button becomes unselected.
- If an already-selected button is clicked, nothing happens; it is not unselected (analogous to a radio button)
For the "multiselect toggles" variant:
- Multiple buttons can be selected at the same time. When a button is clicked, it becomes selected, and any other buttons that might already be selected stay selected
- If an already-selected button is clicked, it is unselected (analogous to a checkbox)
 |  |
- An initial value can be provided, or an empty array. Nothing will be selected by default.
Documentation
- Structure: ToggleButtonGroup is part of the "Button" sidebar group
- Content:
- A demo with five toggle buttons in single-select mode, each of which displays a number (see the "single selection" image above)
- A demo with three toggle buttons in mulitselect mode
- A demo with three icon-only toggle buttons in single-select mode. This demo should contain text that explains that icons should be used consistently in button groups, e.g. no buttons have icons, all buttons have icons and text, or all buttons are icon-only. It should also explain that buttons should only be icon-only if self-explanatory icons are used. See the design spec for a good example.
- A maximum example with 5 toggle buttons in single-select mode. At least one of the buttons should have a very long label and the button group should break to two rows.
- A configurable demo is not recommended for this component.
Considerations
Not in scope:
- Groups of toggle quiet buttons are not in scope for the MVP
- Enforcing a maximum number of buttons by moving the stacked buttons to a different solution is not in scope for the MVP
Open questions:
- How does the parent choose which variant to use? Does it pass in a prop? What is that prop called?
- Should the ToggleButtonGroup (1) create its child buttons itself based on a data object describing each button (like how Menu creates its child MenuItems), or (2) should its child buttons be created by the ToggleButtonGroup's parent and passed into the default slot?
- If (2), how will we manage the mutual exclusivity of buttons in a "single-select" ToggleButtonGroup, and how will we aggregate the value of the selected button(s) in a "single-select" or "multiselect" ToggleButtonGroup? Could we use a similar strategy as radio buttons and checkboxes, where we bind the same v-model on all toggle buttons in a group?
- If (2), is there even a point in having a ToggleButtonGroup component? Would the component do anything at all, other than apply styles? Is it possible for the component to cleverly manage buttons that have been passed into it through a slot, perhaps by using slot parameters or by doing something like what Tabs does?
See T311537 for more info. The outcome of that task will determine the API for both ToggleButtonGroup and ActionButtonGroup.
Acceptance criteria
This task will pass from the designer to the developer once the Figma spec is created.
- A Figma spec sheet is created for the component that includes the scope defined here. A link to the Figma spec sheet's MVP version has been added to this task's description.
- The initial component is implemented in Codex.
Design Review
-
Add configurable demo in the pageIt won't be part of the MVP - Add the following examples in the demo
- Icon-only
- With icon
- Maximum examples (same as here)
- Fix stacked buttons
Test Cases
Existing test cases for reference
- Test maximum cases:
- Entering a long text as a button label - would this truncate or uniformly expand all buttons in the group?
- When there is not enough horizontal space for all buttons the rest of buttons must be stacked
- Consistent button state across major browsers - there has been some history of visual differences seen in Safari 15.1.
