Button

Button is used to initiate actions on a page or form.

Page navigation navigation

Buttons allow users to initiate an action or command when clicked or tapped. The Button's label or text description indicates the purpose of the action to the user. At GitHub, buttons are a fundamental building block of our products. Most of the time, we use the secondary variant, but other variants of buttons may be used to indicate something special about the Button's hierarchy or functionality.

Anatomy

Inactive buttons

A Button that looks like a disabled primary Button, but it has a focus state

An inactive Button has styles that make the Button appear "muted". The style is the same for all Button variants.

An inactive Button is an accessible alternative to a disabled Button. They're intended to be used for buttons that are non-functional, but cannot be removed from the page.

Unlike a disabled Button, an inactive Button can respond to user input. For example, if a Button shows a tooltip when hovered or focused, or a Dialog when clicked.

If you need to use an inactive Button, it's best to have something else on the page that informs users about the issue that broke the Button's normal functionality. For example, showing a global Banner for service outages.

Ways an inactive Button should respond to user input

Show a Dialog on click: When a user tries to activate an inactive the Button, open a Dialog that explains why the action cannot be completed and give them a path forward if possible. It is required to provide some kind of feedback when a user clicks a Button.
Show a tooltip on hover or focus: Before a user tries to activate a non-functional control, a Tooltip with additional context may be displayed on hover or focus. It is not required to respond to hover and focus.

Best practices

Primary variant

Only use one primary Button on a page, whenever possible, to indicate its emphasis relative to other actions.

General

A Button with no line breaks — Keep Button labels succinct with no line breaks.

Don’t

A Button with a line break — Buttons should never contain line breaks and lose their Button shape.

A Button using sentance case — Use sentence case for labels.

Don’t

A Button with text in all caps — Don't use all-caps or other text formats.

A Button showing :focus state — Show focus styles on keyboard :focus

Don’t

A Button with the default :focus styles removed — Don't remove default Button :focus styles.

Primary Button placed at the end of the ButtonGroup — Do place primary buttons at the end of a ButtonGroup

Don’t

Primary Button placed at the start of the ButtonGroup — Don't place primary buttons at the start of a ButtonGroup

A primary Button next to a secondary Button — Use a primary Button with a secondary Button

Don’t

Multiple primary buttons placed together — Don't place multiple primary buttons together

Selections

Buttons are commonly used to show a choice within a SelectPanel or ActionMenu. In such instances, they are frequently paired with an internal or external label.

Two examples of dropdown buttons are shown. The left one has a label 'Visibility: Everybody' and is marked as 'Internal label'. The right one has an external label 'Visibility' above the Button and a internal label 'Everybody', and is marked as 'External Label'.

When dealing with multiple selections, it's essential to maintain clarity regarding the total selection at all times. We suggest showing the value directly within the Button. However, in scenarios where multiple items are selected, transitioning to a format such as 2 selected is advisable.

Button with label 'Labels: 2 selected' — Use the '2 selected' format when multiple items are selected

Don’t