Toggle button group
A toggle button group joins several toggle buttons into one toolbar, where any number can be on at once.
<tk-toggle-button-group label="Text formatting"> <tk-toggle-button value="bold" pressed><tk-button variant="ghost">Bold</tk-button></tk-toggle-button> <tk-toggle-button value="italic"><tk-button variant="ghost">Italic</tk-button></tk-toggle-button> <tk-toggle-button value="underline"><tk-button variant="ghost">Underline</tk-button></tk-toggle-button> </tk-toggle-button-group>
Anatomy
| Part | What it is |
|---|---|
tk-toggle-button-group |
the element; role="toolbar"; one Tab stop for the whole group |
| default slot | two or more tk-toggle-buttonvalue |
| end caps and seams | the same joined geometry as a |
Layout
The group lays out its toggles exactly like a
- Joined (default) or
spaced: one block with a 1px line between toggles, or separate toggles with an 8px gap. orientation="vertical": a column; the arrow keys follow it.shape="round": pill end caps, or 16px caps on a vertical block. Set it on the group, not on the inner buttons.
<tk-toggle-button-group shape="round" label="Filters"> <tk-toggle-button value="unread" pressed><tk-button>Unread</tk-button></tk-toggle-button> <tk-toggle-button value="starred"><tk-button>Starred</tk-button></tk-toggle-button> <tk-toggle-button value="mentions" pressed><tk-button>Mentions</tk-button></tk-toggle-button> </tk-toggle-button-group>
Sizes
Set size once on the group and every toggle takes it: small, medium, or large, 24,
32, or 36px tall, like
<tk-toggle-button-group size="small" label="View"> <tk-toggle-button value="grid"><tk-button>Grid lines</tk-button></tk-toggle-button> <tk-toggle-button value="rulers"><tk-button>Rulers</tk-button></tk-toggle-button> </tk-toggle-button-group>
States
<tk-toggle-button-group disabled label="Alignment guides"> <tk-toggle-button value="snap" pressed><tk-button>Snap</tk-button></tk-toggle-button> <tk-toggle-button value="guides"><tk-button>Guides</tk-button></tk-toggle-button> </tk-toggle-button-group>
disabled: disables every toggle, and the group drops out of the Tab order. A toggle you disabled on its own stays disabled when the group is enabled again.- Each toggle's on state and look come from
Toggle button .
Value
valueis a property holding the array of the pressed toggles'values, such as["bold", "underline"]. Setting it presses exactly those toggles.changefires once each time a user flips a toggle. Readevent.target.value. Settingvalueorpressedin code fires nothing.
When to use
- Use a toggle button group for related toggles where any number can be on, such as a formatting bar or a set of view filters.
- Use a
Segmented control when exactly one option is on. - Use a
Button group for one-off commands that don't stay on. - Use a
Checkbox group when the choices are submitted with a form. - Use a
Tab bar to switch sections or panels.
Content
labelnames the toolbar: "Text formatting", "Filters". The group warns in the console when it's missing.- Keep the toggle labels stable, as on any
Toggle button . - Keep it to 2 to 6 toggles. Put more in a
Menu .
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Use it where several toggles can be on | Use it where exactly one must be on; use a segmented control |
Give each toggle a value and read the group's value |
Track each toggle by hand to get the pressed set |
Name the toolbar with label |
Leave a toolbar unnamed |
| Keep 2 to 6 toggles | Crowd a toolbar; move extras to a menu |
| Use it for modes and filters | Use it for a form value; use checkboxes |
Related
Toggle button : each member.Button group : the same layout for one-off commands.Segmented control : exactly one option on.Checkbox : several choices submitted with a form.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
label |
string | required | accessible name for the toolbar |
orientation |
horizontal | vertical |
horizontal |
a row or a column; sets aria-orientation and the arrow keys |
spaced |
boolean | false |
separate toggles with an 8px gap instead of one block |
shape |
rect | round |
rect |
rounded or pill end caps; the middle stays square |
size |
small | medium | large |
unset | sets the size of every toggle |
disabled |
boolean | false |
disables every toggle |
Properties
| Property | Type | What it does |
|---|---|---|
value |
string[] |
the pressed toggles' values; setting it presses exactly those |
Slots
| Slot | Content |
|---|---|
| default | two or more tk-toggle-button, each with a value |
Events
| Event | When |
|---|---|
change |
a user flips a toggle; bubbles, can't be canceled. Read event.target.value |
Tokens
The toggles draw their own colors: see border/subtle seam, radius-8
end caps (radius-full, or radius-16 when vertical, with shape="round"), and a
space-8 gap when spaced.
Accessibility
Built in:
role="toolbar"witharia-orientation, named bylabel.- One Tab stop: Tab enters the group on the last focused toggle and leaves it on the next press.
- Arrow keys move focus only; they never toggle. Disabled toggles are skipped.
- Each toggle has its own
aria-pressed. - A focused toggle comes to the front, so its focus ring is never cut off at a seam.
Your part:
- Name the toolbar with
label. - Give each toggle a stable label and a
value.
| Key | Action |
|---|---|
Tab |
enters or leaves the group |
Left / Right |
moves focus in a row, wrapping at the ends |
Up / Down |
moves focus in a column, wrapping at the ends |
Home / End |
moves focus to the first / last toggle |
Space / Enter |
flips the focused toggle |