Anatomy elements
#	Required	Element	Description
1		Group	Wraps two or more Buttons and decides whether they connect or separate. When separated, applies gap spacing between the Buttons.
2		Button	A single action in the group.

ButtonGroups wrap two or more Buttons together to treat them as a unified set of related actions. Grouping also allows the Buttons to inherit props for variant, size, and disabled state. Buttons may either be connected (segmented) or spaced.

ButtonGroup vs. Tabs

ButtonGroups and Tabs both use an inline set of buttons to perform a task. Be sure to understand the difference between them as they are not interchangeable:

ButtonGroups display a set of closely-related actions together, either segmented or separated.
Tabs are lists of buttons used to group content under different panels to make information easier to understand.

Segmented vs. spaced

Buttons may be rendered as a segmented, "single" group or separated with gap spacing. Use the segmented variant when the actions are closely-related within a single context, such as zoom controls, as a WYSIWYG editing toolbar, forward and back buttons, etc. Use the spaced variant for form submission and cancellation or actions within a modal's footer.

Best practices

Consistency

Consistency matters. Avoid mixing sizes or variants on individual Buttons to maintain a clean interface.

Do: Maintain consistent props between Buttons.

Don't: Mix props between Buttons.

Group size

Limit group size to four Buttons maximum. A larger group is more difficult to scan as the Buttons take up more space on the page. Consider placing extra actions into a contextual DropdownMenu, or pairing the main action with one in a split button.

Toolbars with Icon-only Buttons may include more visible Buttons before the rest are placed within a DropdownMenu.

Do: Limit group size for the majority of cases.

Don't: Display every available action in one group.

Do: Use a split button to keep secondary actions available without overloading the group.

Importance

Primary Buttons serve the purpose of highlighting the most important action a user may take on the current page. When placing Buttons in forms or where users are expected to complete a task, be mindful to set each action at the most appropriate importance level. Actions are displayed from most to least important starting from right to left.

Avoid placing more than one Primary Button within a workflow or page.

Do: Put the confirming action last and give it the only primary treatment.

Don't: Lead with the confirming action or repeat the primary treatment.

Configurations

When using ButtonGroups, consider the following common configurations before creating a new design standard.

Icon toolbar

A segmented group of Icon-only Buttons acts as a compact toolbar for actions on a canvas or preview. Provide each Button an accessible label as there's no visible text.

Paired actions

Paired actions are the most common configuration, providing the user a way to accept or reject changes being made in the given context.

Pagination controls

Pagination displays as a segmented collection of items used to help users navigate through sets of data in the form of pages.

Split button

Split buttons are used to display one main action with other contextual actions relegated to an adjacent DropdownMenu.

Appearance

Variants

Segmented

Buttons connect into a single, segmented control with overlapping borders.

Spaced

Buttons maintain their default styling and have space-100 between them.

Icons

Icon-only ButtonGroups are used for toolbars. Use icons consistently—if one Button has an icon, they must all have icons.

Icons paired with labels are best suited for communicating actions that will take place.

Icon only

Visible labels may be omitted for commonly-used icons.

Icon with label

Provide a label with less-common icons or to better communicate the action taking place.

Sizes

ButtonGroups come in two sizes: medium and small. Setting the size on the group overrides the size prop set on the individual Button to maintain consistency.

Medium

Medium is the default size used in the majority of cases.

Small

Small groups are used for smaller screen sizes and less prominent actions on the page.

Behaviors

States

Base

The base Button uses the default variant colors when no user interaction is detected.

Hover

On mouse hover, Button styles update to hover colors.

Focus

Focused Buttons receive the standard 2px light blue outline.

Active

On user activation, Button styles update on user activation.

Disabled

Disabled Buttons cannot be interacted with. Lighter colors are used for all variants.

Shared configuration

Buttons within the group inherit the variant, size, and disabled state through component props. Each prop functions slightly differently:

Variant allows Buttons with their own defined variant prop to maintain it. Buttons with no set variant will adopt the group's setting.
Size set by the group always overrides the individual Button's setting. This is important for maintaining a consistent visual hierarchy.
Disabled state is applied to all Buttons when set by the group. However, a single Button's disabled state will remain disabled even when the group as a whole is enabled.

Group defaults

Buttons adhere to the group's settings.

Per-Button override

Individual Buttons may opt out of the variant set by the group.

Content

Button labels are written consistently across the application. For more information on writing labels, see the Content section on the Button page.

ButtonGroup

Anatomy

Guidelines

When to use