Layr
⌘K
Ctrl K
Design Systems
AI Designer
Account
Roadmap
Sign in
Getting started
Github Primer
Primer UI
Pro
Components
Action Bar
Action List
Action Menu
Anchored Overlay
Autocomplete
Avatar
Avatar Pair
Avatar Stack
Banner
Blankslate
Border Box
Box
Branch Name
Breadcrumbs
Button
Button Group
Button Marketing
Checkbox
Checkbox Group
Circle Badge
Circle Octicon
Clipboard Copy
Clipboard Copy Button
Close Button
Comment Box
Counter Label
Data Table
Details
Dialog
Form Control
Header
Heading
Hidden Text Expander
Icon
Icon Button
Image
Inline Message
Label
Label Group
Layout
Link
Markdown
Nav List
Octicon Symbols
Overlay
Page Header
Page Layout
Pagehead
Pagination
Pointer Box
Popover
Progress Bar
Radio
Radio Group
Relative Time
Segmented Control
Select
Selectpanel
Skeleton Avatar
Skeleton Box
Skeleton Text
Spinner
Split Page Layout
Stack
State Label
Subnav
Tab Container
Tab Nav
Tab Panels
Text
Text Input
Text Input With Tokens
Textarea
Timeline
Timeline Item
Toggle Switch
Token
Tooltip
Tree View
Truncate
Underline Nav
Underline Panels
<li>For most use-cases, only default button types should be used in button groups. In rare cases, primary buttons can be included in button groups but there should only ever be one primary button (if any) in a button group.</li> <li>Avoid grouping too many buttons together. It could be overwhelming to the user.</li> <li>Do not use a button group to indicate a selection. Use a <a href="/components/segmented-control" class="Link">segmented control</a> instead.</li> <li>Do not use a button group as a replacement for <a href="/components/tab-nav" class="Link">tab navigation</a>.</li> <li>Avoid mixing buttons with text labels with icon-only buttons. However, it is acceptable to group a text-labeled button with an icon-only button with a down-pointing triangle that opens a dropdown menu of actions related to the button.</li> <li>Do not group an <a href="/components/button#invisible" class="Link">invisible</a> button with buttons of another variant.</li> </ul> </div> </div> <!-- Options Section --> <div class="component-section"> <h2 class="h2 mb-3">Options</h2> <!-- Size Demo --> <div class="demo-section"> <div class="demo-title">Size</div> <div class="demo-description">Button groups only support medium (default) and small button sizes.</div> <div class="demo-row"> <div class="size-label">Medium (default)</div> <div class="BtnGroup"> <button class="btn BtnGroup-item" type="button">Button</button> <button class="btn BtnGroup-item" type="button">Button</button> <button class="btn BtnGroup-item" type="button">Button</button> </div> </div> <div class="demo-row"> <div class="size-label">Small</div> <div class="BtnGroup"> <button class="btn btn-sm BtnGroup-item" type="button">Button</button> <button class="btn btn-sm BtnGroup-item" type="button">Button</button> <button class="btn btn-sm BtnGroup-item" type="button">Button</button> </div> </div> </div> <!-- Split Button Demo --> <div class="demo-section"> <div class="demo-title">Split buttons with a dropdown</div> <div class="demo-description">A button group can be shown as a split button with an action on the left and dropdown button with an additional list of actions.</div> <div class="demo-row"> <div class="BtnGroup"> <button class="btn btn-primary BtnGroup-item" type="button">Create merge commit</button> <button class="btn btn-primary BtnGroup-item" type="button" aria-label="More options"> <svg class="octicon octicon-triangle-down" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"> <path d="m4.427 7.427 3.396 3.396a.25.25 0 0 0 .354 0l3.396-3.396A.25.25 0 0 0 11.396 7H4.604a.25.25 0 0 0-.177.427Z"></path> </svg> </button> </div> </div> </div> <!-- Leading and Trailing Visuals Demo --> <div class="demo-section"> <div class="demo-title">Leading and trailing visuals</div> <div class="demo-description">Similarly to buttons, button segments can optionally include an icon and/or a counter.</div> <div class="demo-row"> <div class="BtnGroup"> <button class="btn BtnGroup-item" type="button"> <svg class="octicon octicon-eye mr-1" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"> <path d="M8 2c1.981 0 3.671.992 4.933 2.078 1.27 1.091 2.187 2.345 2.637 3.023a1.62 1.62 0 0 1 0 1.798c-.45.678-1.367 1.932-2.637 3.023C11.67 13.008 9.981 14 8 14c-1.981 0-3.671-.992-4.933-2.078C1.797 10.83.88 9.576.43 8.898a1.62 1.62 0 0 1 0-1.798c.45-.677 1.367-1.931 2.637-3.022C4.33 2.992 6.019 2 8 2ZM1.679 7.932a.12.12 0 0 0 0 .136c.411.622 1.241 1.75 2.366 2.717C5.176 11.758 6.527 12.5 8 12.5c1.473 0 2.825-.742 3.955-1.715 1.124-.967 1.954-2.096 2.366-2.717a.12.12 0 0 0 0-.136c-.412-.621-1.242-1.75-2.366-2.717C10.824 4.242 9.473 3.5 8 3.5c-1.473 0-2.825.742-3.955 1.715-1.124.967-1.954 2.096-2.366 2.717ZM8 10a2 2 0 1 1-.001-3.999A2 2 0 0 1 8 10Z"></path> </svg> Watch </button> <button class="btn BtnGroup-item" type="button"> <svg class="octicon octicon-star mr-1" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"> <path d="M8 .25a.75.75 0 0 1 .673.418l1.882 3.815 4.21.612a.75.75 0 0 1 .416 1.279l-3.046 2.97.719 4.192a.75.75 0 0 1-1.088.791L8 12.347l-3.766 1.98a.75.75 0 0 1-1.088-.79l.72-4.194L.818 6.374a.75.75 0 0 1 .416-1.28l4.21-.611L7.327.668A.75.75 0 0 1 8 .25Zm0 2.445L6.615 5.5a.75.75 0 0 1-.564.41l-3.097.45 2.24 2.184a.75.75 0 0 1 .216.664l-.528 3.084 2.769-1.456a.75.75 0 0 1 .698 0l2.77 1.456-.53-3.084a.75.75 0 0 1 .216-.664l2.24-2.183-3.096-.45a.75.75 0 0 1-.564-.41L8 2.694Z"></path> </svg> Star <span class="Counter ml-1">1.2k</span> </button> <button class="btn BtnGroup-item" type="button"> <svg class="octicon octicon-repo-forked mr-1" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"> <path d="M5 5.372v.878c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.878a2.25 2.25 0 1 1 1.5 0v.878a2.25 2.25 0 0 1-2.25 2.25h-1.5v2.128a2.251 2.251 0 1 1-1.5 0V8.5h-1.5A2.25 2.25 0 0 1 3.5 6.25v-.878a2.25 2.25 0 1 1 1.5 0ZM5 3.25a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Zm6.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm-3 8.75a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0Z"></path> </svg> Fork <span class="Counter ml-1">234</span> </button> </div> </div> </div> </div> <!-- Accessibility Section --> <div class="component-section"> <h2 class="h2 mb-3">Accessibility</h2> <h3 class="h3 mb-3">As toolbar</h3> <p class="mb-3">By default, a button group does not behave like a <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/toolbar_role" class="Link" target="_blank">toolbar</a>, so assistive technologies still interpret the buttons as unrelated. The grouping is purely visual.</p> <p class="mb-3">If you want to make the button group behave like a toolbar, you can add the <code>role="toolbar"</code> prop to the <code>ButtonGroup</code> component. This will communicate the appropriate role to assistive technologies.</p> <p class="mb-4">When <code>role="toolbar"</code> is used, individual buttons aren't separately focusable. Instead, only one button receives focus, and users switch between all buttons in the toolbar using the cursor keys. This behavior is baked into the component.</p> <div class="accessibility-note"> <p class="mb-2"><strong>Note:</strong> The toolbar keyboard interaction behaviors are currently implemented in Primer React only, and are not available in Primer View Components.</p> </div> <!-- Toolbar Demo --> <div class="demo-section"> <div class="demo-title">Toolbar example</div> <div class="demo-description">Button group with toolbar role for assistive technologies.</div> <div class="demo-row"> <div class="BtnGroup" role="toolbar" aria-label="Text formatting"> <button class="btn BtnGroup-item" type="button" aria-label="Bold"> <svg class="octicon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"> <path d="M4 2a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h5.5a3.5 3.5 0 0 0 1.852-6.47A3.5 3.5 0 0 0 8.5 2H4Zm4.5 5a1.5 1.5 0 1 1 0-3H5.25v3H8.5ZM5.25 9v3H9.5a1.5 1.5 0 0 1 0 3H5.25Z"></path> </svg> </button> <button class="btn BtnGroup-item" type="button" aria-label="Italic"> <svg class="octicon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"> <path d="M6 2.75A.75.75 0 0 1 6.75 2h6.5a.75.75 0 0 1 0 1.5h-2.505l-3.858 9H9.25a.75.75 0 0 1 0 1.5h-6.5a.75.75 0 0 1 0-1.5h2.505l3.858-9H6.75A.75.75 0 0 1 6 2.75Z"></path> </svg> </button> <button class="btn BtnGroup-item" type="button" aria-label="Underline"> <svg class="octicon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"> <path d="M2 14a.75.75 0 0 1 .75-.75h10.5a.75.75 0 0 1 0 1.5H2.75A.75.75 0 0 1 2 14ZM3.5 2.75a.75.75 0 0 1 1.5 0V8a3 3 0 0 0 6 0V2.75a.75.75 0 0 1 1.5 0V8a4.5 4.5 0 0 1-9 0V2.75Z"></path> </svg> </button> </div> </div> </div> <h3 class="h3 mb-3">Descriptive buttons</h3> <p class="mb-3">Labeling buttons properly lets users know what will happen when they activate the control, lessens errors, and increases confidence.</p> <p class="mb-4">Read more about <a href="/guides/accessibility/descriptive-buttons" class="Link">descriptive buttons</a>.</p> <h3 class="h3 mb-3">Known accessibility issues (GitHub staff only)</h3> <p class="mb-4"> <a href="#" class="Link">ButtonGroup accessibility issues</a> </p> </div> <!-- Related Links --> <div class="component-section"> <h2 class="h2 mb-3">Related links</h2> <ul> <li><a href="/components/button" class="Link">Button</a></li> <li><a href="/components/segmented-control" class="Link">Segmented control</a></li> </ul> </div> <!-- Feedback Section --> <div class="component-section"> <h2 class="h2 mb-3">Feedback</h2> <p>Help us improve this component by providing feedback, asking questions on Slack, or updating this file on GitHub.</p> </div></body></html>' width="100%" height="2400" frameborder="0" sandbox="allow-scripts allow-same-origin allow-popups">