Button group
A button group joins related buttons into one block, or spaces them evenly. Each button stays its own action; the group holds no value.
<tk-button-group label="Text alignment"> <tk-button>Left</tk-button> <tk-button>Center</tk-button> <tk-button>Right</tk-button> </tk-button-group>
Anatomy
| Part | What it is |
|---|---|
tk-button-group |
the element; role="group"; a row or a column |
| default slot | two or more tk-button or tk-icon-button; each keeps its own label, variant, and tone |
| end caps | the outer corners of the first and last button |
| seams | square inner corners and a 1px line between joined buttons |
Layout
Joined and spaced
By default the buttons join into one block. The group squares the inner corners and draws
the line between buttons, so any variant works. Add spaced for separate buttons with an
8px gap, such as Save and Cancel. A joined row's corners assume left-to-right, so use
spaced in a right-to-left layout.
<tk-button-group spaced label="Form actions"> <tk-button variant="primary">Save changes</tk-button> <tk-button>Cancel</tk-button> </tk-button-group>
Orientation
orientation="vertical" stacks the buttons in a column, all as wide as the widest.
<tk-button-group orientation="vertical" label="Row actions"> <tk-button>Edit</tk-button> <tk-button>Duplicate</tk-button> <tk-button>Archive</tk-button> </tk-button-group>
Shape
Set shape="round" on the group, not on the buttons. The end caps round into a pill and the
middle corners stay square. A vertical block gets 16px caps instead. In a spaced group,
every button becomes a pill. A button's own shape has no effect in a joined group.
<tk-button-group shape="round" label="Zoom"> <tk-button>25%</tk-button> <tk-button>50%</tk-button> <tk-button>100%</tk-button> </tk-button-group>
Sizes
<tk-button-group size="small" label="Pages"> <tk-button>Previous</tk-button> <tk-button>Next</tk-button> </tk-button-group>
Set size once on the group and every button takes it: small, medium, or large, 24,
32, or 36px tall, like
States
<tk-button-group disabled label="Pages"> <tk-button>Previous</tk-button> <tk-button>Next</tk-button> </tk-button-group>
disabled: disables every button. A button you disabled on its own stays disabled when the group is enabled again. You can also disable single buttons.- Hover, press, and focus belong to each button. In a joined block the focused button comes to the front, so its focus ring is never cut off.
When to use
- Use a button group for a small set of related actions, usually 2 to 5, each shown as its own button: a toolbar, a pager, zoom controls.
- Use a
Segmented control when one option stays selected, such as List or Grid. - Use a
Toggle button group for several on and off states, such as Bold, Italic, Underline. - Use a
Tab bar to switch sections or panels. - Use a
Split button when one action leads and the rest can wait in a menu.
Content
- Group related commands only. Unrelated actions don't belong in one group.
- Use one variant in a joined block. Mixing works, but the block reads best as one.
- Name the group by what its buttons share with
label: "Text alignment", "Zoom". - Label each button as any
Button . More inAction labels .
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
| Group 2 to 5 related commands | Put unrelated actions in one group |
| Let the group draw the line between buttons | Add your own divider between them |
| Use a segmented control when one option stays selected | Use a button group to hold a value |
Set size once on the group |
Mix sizes in a joined block |
Set shape="round" on the group |
Set it on the buttons in a joined group |
Related
Segmented control : one choice that stays selected.Toggle button group : several on and off states.Tab bar : switches sections or panels.Split button : one leading action and a menu.Page header : a page's actions as a spaced group.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
orientation |
horizontal | vertical |
horizontal |
a row or a column |
spaced |
boolean | false |
separate buttons 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 button |
disabled |
boolean | false |
disables every button |
label |
string | unset | accessible name for the group |
Slots
| Slot | Content |
|---|---|
| default | two or more tk-button or tk-icon-button; for one, use a plain button |
Events
No custom events. Listen for click on each button.
Tokens
| Part | Token |
|---|---|
| buttons | |
| seam | border/subtle |
| end caps | radius-8; with shape="round", radius-full, or radius-16 when vertical |
gap in spaced |
space-8 |
Accessibility
Built in:
role="group", named bylabel.- Each button is its own Tab stop, with no arrow-key movement, like buttons placed side by side.
- The group holds no value: no
aria-pressedand noaria-checked.
Your part:
- Name a dense toolbar with
label; it's optional, since each button has its own name. - Use a
Segmented control orTab bar when the choice stays selected.
| Key | Action |
|---|---|
Tab |
moves to the next button |
Space / Enter |
activates the focused button |