Start an action
Use buttons for actions such as submitting, saving, opening, or confirming.
Components
Button
Custom button styles for actions in forms, dialogs, and more with support for multiple sizes, states, and more.
Show action hierarchy
Variants help users identify the main action and secondary choices.
Cover common states
Loading, disabled, and focus states keep button behaviour predictable.
1
Container
2
Label
3
Left icon (optional)
4
Right icon (optional)
Variants
Button variants communicate hierarchy and help users identify the primary action on a screen.
Use for the main action on a screen. Each view should have only one primary button to communicate the next step.
Tone
Button tone changes the colour treatment within the selected variant so the action can match the surrounding context.
The default button tone. Use for standard actions in the main SGDS brand colour system.
Size
Button sizes let you match the visual weight of the action to the density of the surrounding layout.
The default size. Use for most primary actions across forms, dialogs, and general page content.
Leading icon
A leading icon sits to the left of the button label and reinforces the meaning of the action.
Use a leading icon when the icon adds clarity to the action. For example, a download icon before a download label.
Trailing icon
A trailing icon sits to the right of the button label and is typically used to signal direction or progression.
Use a trailing icon to indicate navigation, forward movement, or that a menu or panel will open.
State
Buttons expose disabled, loading, and active states for common interaction feedback.
Use for actions that are available immediately.
Full width
Full width makes the button fill its parent container for stacked or narrow layouts.
Use the default width for inline actions.
Design tokens used
Each row is a colour, spacing, or size value the component uses, and the right-most column tells you where in the component you'll see it.
sgds-border-radius-md8pxsgds-border-width-11pxsgds-gap-none0pxsgds-dimension-4848pxsgds-dimension-9696pxsgds-font-size-label-md16pxsgds-color-fixed-light#F3F3F3sgds-color-fixed-light#F3F3F3sgds-padding-lg20pxsgds-dimension-4848pxsgds-dimension-9696pxsgds-font-size-label-md16pxsgds-line-height-xs24pxWhen to use
- Use button for a clear action that changes the page, saves progress, or moves the task forward.
- Use the button variant that matches the importance of the action.
When not to use
- Do not use button for navigation when a link would be clearer.
- Do not use vague labels that force users to guess what happens next.
Use a clear action label
Specific labels help users understand the outcome before they act.
Do not use vague labels
Generic labels such as Click here force users to read surrounding text to understand what happens.
Built-in accessibility
- Buttons render as native buttons by default and anchors when
hrefis provided. - The component exposes
disabledand loading states to assistive technology.
Labels and content
- Use button text that describes the action.
- Add an accessible label when the visible text is replaced by an icon or loading state.
Focus and interaction
- Keep buttons in the same order as the task flow.
- Do not use a
disabledbutton as the only way to explain what users need to do next.
TabShift+TabEnterSpaceHave suggestions or feedback?
Share them with us on Slack → #ask-sgds-v3
Found a bug or issue?
Report it on GitHub Issues → sgds/components/button