Button group
Visually and programmatically groups a small collection of related buttons.
On this page
This docs is LLM-friendly and available as clean Markdown.
Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more
Usage
import { GlButton } from "gitlab-ui-react/button";
import { GlButtonGroup } from "gitlab-ui-react/button-group";<GlButtonGroup>
<GlButton>Download</GlButton>
<GlButton>Browse</GlButton>
</GlButtonGroup>Default
Use a button group for two to five closely related actions. Keep the controls visually consistent, and consider a disclosure dropdown when three or more actions would consume too much space.
import { GlButton } from "gitlab-ui-react/button";
import { GlButtonGroup } from "gitlab-ui-react/button-group";
export default function ButtonGroupExample() {
return (
<GlButtonGroup>
<GlButton>Download</GlButton>
<GlButton>Browse</GlButton>
<GlButton variant="danger">Delete</GlButton>
</GlButtonGroup>
);
}
Related options
A group can switch between mutually exclusive views or update content in place. Manage the selection in the parent and keep each button’s selected appearance synchronized with aria-pressed.
import { useState } from "react";
import { GlButton } from "gitlab-ui-react/button";
import { GlButtonGroup } from "gitlab-ui-react/button-group";
export default function ButtonGroupSelectedExample() {
const [selectedView, setSelectedView] = useState<"list" | "board">("list");
return (
<GlButtonGroup>
<GlButton
aria-pressed={selectedView === "list"}
onClick={() => setSelectedView("list")}
selected={selectedView === "list"}>
List
</GlButton>
<GlButton
aria-pressed={selectedView === "board"}
onClick={() => setSelectedView("board")}
selected={selectedView === "board"}>
Board
</GlButton>
</GlButtonGroup>
);
}
Vertical layout
Set vertical to stack related controls. Use this variation only when a horizontal group does not fit the layout; split dropdowns are not supported in a vertical group.
import { GlButton } from "gitlab-ui-react/button";
import { GlButtonGroup } from "gitlab-ui-react/button-group";
export default function ButtonGroupVerticalExample() {
return (
<GlButtonGroup vertical>
<GlButton>Download</GlButton>
<GlButton>Browse</GlButton>
<GlButton variant="danger">Delete</GlButton>
</GlButtonGroup>
);
}
Accessibility
GlButtonGroupautomatically rendersrole="group". Keep it near context that makes the relationship between controls clear.- For selectable buttons, set exactly one button’s
selectedandaria-pressedvalues totrueat a time. - When grouped links represent a current local selection, use
aria-current="true". Avoid mixing buttons and links in one group because their behavior differs. - Keep keyboard focus order the same as visual order and decide whether focus should remain on the control or move to updated content after activation.
- Use radio buttons or checkboxes for choices within a form.
API
These are the component-specific props. GlButtonGroup also forwards supported div attributes and a ref. It always sets role="group".
| Prop | Description | Default |
|---|---|---|
vertical |
Stacks the grouped controls vertically. | false |
children |
Provides the related buttons or button-like controls. | — |
className |
Adds classes to the group container. | — |