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

Image displaying each variation of button, from left: Secondary, Primary, Danger, Invisible.


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 "Default" button type, but other types of buttons may be used to indicate something special about the button's hierarchy or functionality.


Anatomy of a button, including the label, leading visual, trailing visual, and trailing action


Leading and trailing visuals

trailing action on a button

Trailing actions

Trailing actions such as dropdown carets are always locked to the end of a button, which is particularly obvious for full width scenarios. If a button is a call-to-action (Submit, Save, Do this™, etc), its contents (visuals and button label) appear center-aligned inside the button container. If a button is used for selecting items (Weeks ▾, Iteration ▾, Sort ▾, Select™ ▾, etc), its contents (visuals and button label) appear left-aligned inside the button container.

leading visual on a button

Leading visuals

Leading visuals provide additional context for a button label, such as a “search” icon next to the label for a search field submit. Leading visuals always apear locked to the button label, even if the button is full width.

trailing visual on a button

Trailing visuals

Trailing visuals such as counters display additional information about the action or task at hand. Trailing visuals always apear locked to the button label, even if the button is full width.

Sizing and spacing

button at medium size

Medium (default)

Primer buttons are medium sized by default. Medium is suitable for most interfaces and is considered the preferred size.

button at small size


Small buttons may be used when space is limited and if the action is less significant.

button at large size


Large buttons increase the significance of an action and should be used sparingly. More often than not a medium sized button will be more appropriate.


Primary button with green background


Primary buttons represent the highest priority action in a page. There should only ever be one primary button (if any) in a button group, and typically only one primary button should be present in page.

Secondary button with gray background


Secondary buttons are the default button color scheme and are suitable for more interactions. They can be paired with a primary button to perform a secondary action, or used on their own.

Invisible button with transparent background


Invisible buttons have a transparent background with translucent hover and active states, making them useful for compound components like ActionList.

Danger button with red background


Danger buttons should be used sparingly to warn of a destructive action, typically resulting in the opening of a confirmation dialog.


An 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 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.

There are two recommended ways an inactive button should respond to user input:

  1. 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.
  2. 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.


An button that looks disabled, but the text is replaced with a spinning loading indicator

You may use a button loading state if we need to wait for a button's action to be completed. Refer to the accessibility section's button loading state guidance for more information.

Best practices

Primary and outline button usage

Limit primary button usage. Only use one primary button on the page, whenever possible, to indicate its emphasis relative to other actions. Primary buttons have top priority in visual hierarchy, and using too many of them on a single view dilutes their effectiveness.

Button usage

An image showing a button with no line breaks

Keep button labels succinct with no line breaks.

An image showing 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.

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

A button with the default :focus styles removed

Don't remove default button :focus styles.

Primary button placed at the end of the button group

Do place primary buttons at the end of a button group

Primary button placed at the start of the button group

Don't place primary buttons at the start of a button group

A primary button next to a secondary button

Use a primary button with a secondary button

Multiple primary buttons placed together

Don’t place multiple primary buttons together


Do not disable buttons

There are rare cases where it's ok to disable a button, but it should generally be avoided. Disabling a button makes it invisible to assistive technologies such as screen readers.

For more information on disabled controls, see GitHub's link and button a11y guidance (GitHub staff only).

Descriptive buttons

Labeling buttons properly lets users know what will happen when they activate the control, lessens errors, and increases confidence.

Read more about descriptive buttons.

Button loading state

A button in a loading state with a11y annotations

When implementing a "loading" button state, don't remove the button from the DOM or pass the disabled attribute. Doing so would make it impossible to tab to the button. If the button was just focused and activated, it would reset focus. Resetting focus would disrupt the keyboard navigation flow, and creates a confusing experience for assistive technologies such as screen readers.

Once the button is activated (and is in a loading state), it get the attribute aria-disabled="true".

A separate, visually hidden element should be rendered outside of the <button> with a message to communicate the loading status. For example, "Saving profile".

This message should be in an ARIA live region, using aria-live="polite". The live region must be present on page load, but the message inside the live region should only be rendered while the button is in a loading state.

If an error prevents process from being completed, focus should be brought to an <h2> (or next relevant heading) of the error banner.

Known accessibility issues (GitHub staff only)

View open accessibility issues related to this component