Button Groups
A button group is a row of buttons treated as one control, sharing a container and answering a single question between them. Three different things ship under that name and they are not interchangeable: a row of peers where exactly one cell is the answer, an ordered walk where the ends outrank the middle, and one or two actions welded to a field they only make sense against.
The join is not decoration. Connected cells share one border and read as a single object, which is what makes the choice exclusive: press another and the first goes off. Separated cells are pills with a gap between them, and that gap is what tells a reader more than one can be on at once, which is why filter rows are built that way. Changing the join changes what the row means rather than how it looks, and a group drawn connected but behaving as a multi-select will be mis-pressed for as long as it exists.
Button group
Best for
Two to six peer options answering one question, where the choice changes a setting rather than the page
Anatomy
One container and one border when connected · 8px-gap pills when separated, and then more than one can be on · three sizes · no primary
Connected: one container and one border, so only one segment can be active. Nothing is emphasised: the row is one control with several answers in it.
Pagination bar
Best for
A group that walks through an ordered set: pages, steps, results
Anatomy
Grey pill track · Previous faded at the start · round number cells with the current one on white · ellipsis for the gap · Next as the primary
An ordered sequence, not a row of peers, so the ends outrank the numbers and the group carries a primary. Page 1 of 17.
Field group
Best for
Actions that only make sense against what is in the field they are welded to
Anatomy
The field's own header, hint and error · one or two buttons left, right or both · connected shares the field's border, separated sits beside it
The actions only make sense against what is in the field, so the group carries the field’s header, hint and error rather than its own.
Billing panel
Best for
The field group where it actually lives: a settings panel that commits
Anatomy
Plan badge over the heading · the field group with its own header, hint and meta · a switch row · who it is billed to · back and a primary that saves
Using Button Groups
Reach for it when
- Two to six peer options answering one question, where the choice changes a setting rather than the page.
- A filter row where several can be on at once and the spacing has to say so before anyone clicks.
- Actions that only make sense against what is in the field beside them: copy a link, pick a date, set a currency.
- An ordered walk through a set where moving forward deserves more weight than the steps between.
Reach for something else when
- Buttons that do unrelated things: space them out or put them behind a menu, so a shared border stops implying they are alternatives to each other.
- More options than a row can carry: a dropdown lists them all without shrinking every label to an ellipsis.
- A destructive action sitting among safe ones: take it out of the group so its confirmation step and its colouring do not have to fight the group's geometry.
Where it shows up
Toolbar view switches
Grid or list, day or week, source or preview. Connected cells, one answer, nothing emphasised: the row exists to show the alternatives as much as it exists to show the current choice.
Filter rows
Separated pills above a result set, with several on at once. The gap does the explaining, telling the reader these toggle independently before anyone has to click one and find out.
Field-side actions
Copy beside a share link, a calendar beside a date, a currency beside an amount. The buttons share the field's border and inherit its header, hint and error, so the whole thing reads as one control.
Settings panels
A billing or workspace panel where a field group sits among switches and a footer that commits. The group is the input; the footer's primary action is the only emphasised thing on the panel.
Questions
Can a button group contain a primary button?
Not in a row of peers. Emphasising one cell answers the question the reader was asked to answer, and the group stops reading as a set of equals. The exception is a group that walks an ordered set, where the ends really do outrank the middle: moving forward is the expected action, and the numbers between are a way of skipping rather than a choice.
How many buttons can a group hold?
Around six before the labels begin fighting for room. Past that, a dropdown carries the options without widening the row. When a group does run out of space, let it wrap onto a second line rather than scroll, since a scrolling group hides its own options behind a gesture, and a set that has become two rows should lose the full pill radius that only made sense as one.
Premium components,
free in your inbox.
Join the Orvain Dispatch and get production-ready components, free to keep: React and Vue code plus the Figma frame, yours to ship.
Orvain MCPButton Groups
A button group is a row of buttons treated as one control, sharing a container and answering a single question between them. Three different things ship under that name and they are not interchangeable: a row of peers where exactly one cell is the answer, an ordered walk where the ends outrank the middle, and one or two actions welded to a field they only make sense against.
The join is not decoration. Connected cells share one border and read as a single object, which is what makes the choice exclusive: press another and the first goes off. Separated cells are pills with a gap between them, and that gap is what tells a reader more than one can be on at once, which is why filter rows are built that way. Changing the join changes what the row means rather than how it looks, and a group drawn connected but behaving as a multi-select will be mis-pressed for as long as it exists.
Button group
Best for
Two to six peer options answering one question, where the choice changes a setting rather than the page
Anatomy
One container and one border when connected · 8px-gap pills when separated, and then more than one can be on · three sizes · no primary
Connected: one container and one border, so only one segment can be active. Nothing is emphasised: the row is one control with several answers in it.
Pagination bar
Best for
A group that walks through an ordered set: pages, steps, results
Anatomy
Grey pill track · Previous faded at the start · round number cells with the current one on white · ellipsis for the gap · Next as the primary
An ordered sequence, not a row of peers, so the ends outrank the numbers and the group carries a primary. Page 1 of 17.
Field group
Best for
Actions that only make sense against what is in the field they are welded to
Anatomy
The field's own header, hint and error · one or two buttons left, right or both · connected shares the field's border, separated sits beside it
The actions only make sense against what is in the field, so the group carries the field’s header, hint and error rather than its own.
Billing panel
Best for
The field group where it actually lives: a settings panel that commits
Anatomy
Plan badge over the heading · the field group with its own header, hint and meta · a switch row · who it is billed to · back and a primary that saves
Using Button Groups
Reach for it when
- Two to six peer options answering one question, where the choice changes a setting rather than the page.
- A filter row where several can be on at once and the spacing has to say so before anyone clicks.
- Actions that only make sense against what is in the field beside them: copy a link, pick a date, set a currency.
- An ordered walk through a set where moving forward deserves more weight than the steps between.
Reach for something else when
- Buttons that do unrelated things: space them out or put them behind a menu, so a shared border stops implying they are alternatives to each other.
- More options than a row can carry: a dropdown lists them all without shrinking every label to an ellipsis.
- A destructive action sitting among safe ones: take it out of the group so its confirmation step and its colouring do not have to fight the group's geometry.
Where it shows up
Toolbar view switches
Grid or list, day or week, source or preview. Connected cells, one answer, nothing emphasised: the row exists to show the alternatives as much as it exists to show the current choice.
Filter rows
Separated pills above a result set, with several on at once. The gap does the explaining, telling the reader these toggle independently before anyone has to click one and find out.
Field-side actions
Copy beside a share link, a calendar beside a date, a currency beside an amount. The buttons share the field's border and inherit its header, hint and error, so the whole thing reads as one control.
Settings panels
A billing or workspace panel where a field group sits among switches and a footer that commits. The group is the input; the footer's primary action is the only emphasised thing on the panel.
Questions
Can a button group contain a primary button?
Not in a row of peers. Emphasising one cell answers the question the reader was asked to answer, and the group stops reading as a set of equals. The exception is a group that walks an ordered set, where the ends really do outrank the middle: moving forward is the expected action, and the numbers between are a way of skipping rather than a choice.
How many buttons can a group hold?
Around six before the labels begin fighting for room. Past that, a dropdown carries the options without widening the row. When a group does run out of space, let it wrap onto a second line rather than scroll, since a scrolling group hides its own options behind a gesture, and a set that has become two rows should lose the full pill radius that only made sense as one.
Related blocks
All blocksPremium components, free in your inbox.
Join the Orvain Dispatch and get production-ready components, free to keep: React and Vue code plus the Figma frame, yours to ship.
