Button

Custom button styles for actions in forms, dialogs, and more with support for multiple sizes, states, and more.

DesignUsageAccessibilityUpdates

Purpose

Trigger actions clearly

Buttons signal to users that something will happen when they click — whether that's submitting a form, opening a modal, or confirming a choice.

Communicate intent with variants

Primary, secondary, outline, and ghost variants let you express hierarchy — guiding users toward the most important action without overloading the page.

Support every state

Built-in loading, disabled, and focus states keep interactions predictable and accessible across all devices and input methods.

Anatomy

Button label
1

Container

2

Label

3

Left icon (optional)

4

Right icon (optional)

Configuration

Variants

Button variants communicate hierarchy and help users identify the most important action on a screen.

Primary action

Use for the main action on a screen. Each view should have only one primary button to clearly communicate the most important next step.

Tone

Button tone changes the colour treatment within the selected variant so the action can match the surrounding context.

Button label

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.

Button label

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.

Button label

Omit the leading icon when the label alone is clear and no visual reinforcement is needed.

Trailing icon

A trailing icon sits to the right of the button label and is typically used to signal direction or progression.

Button label

Omit the trailing icon when the action does not imply movement, navigation, or a follow-up interaction.

Playground

BETA
Button label
Leading iconTrailing icon

Structure

Button label

Component tokens

Component tokens are specific to each component. Use the table title as the prefix: border-radius under sgds/btn means sgds/btn/border-radius.

sgds/btn
CategoryComponent tokenSemantic tokenValueBorderborder-radiussgds/border-radius/md8pxborder-widthsgds/border-width/11pxGapgapsgds/gap/2-xs4px
sgds/btn/xs
CategoryComponent tokenSemantic tokenValuePaddingpadding-xsgds/padding/sm12pxSizeheightsgds/dimension/3232pxmin-widthsgds/dimension/6464pxTypographyfont-sizesgds/font-size/1212pxline-heightsgds/line-height/1616px
sgds/btn/sm
CategoryComponent tokenSemantic tokenValuePaddingpadding-xsgds/padding/md16pxSizeheightsgds/dimension/4040pxmin-widthsgds/dimension/8080pxTypographyfont-sizesgds/font-size/1414pxline-heightsgds/line-height/2020px
sgds/btn/md
CategoryComponent tokenSemantic tokenValuePaddingpadding-xsgds/padding/lg20pxSizeheightsgds/dimension/4848pxmin-widthsgds/dimension/9696pxTypographyfont-sizesgds/font-size/1616pxline-heightsgds/line-height/2424px
sgds/btn/lg
CategoryComponent tokenSemantic tokenValuePaddingpadding-xsgds/padding/xl24pxSizeheightsgds/dimension/5656pxmin-widthsgds/dimension/112112pxTypographyfont-sizesgds/font-size/2020pxline-heightsgds/line-height/3232px
sgds/btn/primary/brand
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/primary/surface-default#6B4FEBhover-bgsgds/primary/surface-emphasis#523ABCtext-and-icon-colorsgds/color-fixed-light#F3F3F3
sgds/btn/primary/danger
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/danger/surface/default#CF2323hover-bgsgds/danger/surface/emphasis#A11B1Btext-and-icon-colorsgds/color-fixed-light#F3F3F3
sgds/btn/primary/neutral
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/surface-inverse#2A2A2Ahover-bgsgds/bg-translucent-inverseoklch(from #FFFFFF l c h / 0.2)text-and-icon-colorsgds/color-inverse#F3F3F3
sgds/btn/primary/fixed-light
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/surface-fixed-light#FFFFFFhover-bgsgds/surface-fixed-light + sgds/bg-translucent-fixed-dark#FFFFFF + oklch(from #0E0E0E l c h / 0.2)text-and-icon-colorsgds/color-fixed-dark#1A1A1A
sgds/btn/outline/brand
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/primary/bg-translucentoklch(from #523ABC l c h / 0.1)text-and-icon-colorsgds/primary/color-default#6B4FEBborder-colorsgds/primary/border-color/default#6B4FEB
sgds/btn/outline/danger
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/danger/surface/translucentoklch(from #A11B1B l c h / 0.08)text-and-icon-colorsgds/danger/color/default#CF2323border-colorsgds/danger/border-color/default#CF2323
sgds/btn/outline/neutral
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/bg-translucent-subtle + sgds/bg-translucent-inverseoklch(from #0E0E0E l c h / 0.05) + oklch(from #FFFFFF l c h / 0.2)text-and-icon-colorsgds/color-default#1A1A1Aborder-colorsgds/border-color/emphasis#3B3B3B
sgds/btn/outline/fixed-light
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/bg-transparent + sgds/bg-translucent-fixed-darkTransparent + oklch(from #0E0E0E l c h / 0.2)text-and-icon-colorsgds/color-fixed-light#F3F3F3border-colorsgds/border-color/fixed-light#FFFFFF
sgds/btn/ghost/brand
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/primary/surface/translucentoklch(from #523ABC l c h / 0.1)text-and-icon-colorsgds/primary/color-default#6B4FEB
sgds/btn/ghost/danger
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/danger/surface/translucentoklch(from #A11B1B l c h / 0.08)text-and-icon-colorsgds/danger/color/default#CF2323
sgds/btn/ghost/neutral
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/bg-translucent-subtleoklch(from #0E0E0E l c h / 0.05)text-and-icon-colorsgds/color-default#1A1A1A
sgds/btn/ghost/fixed-light
CategoryComponent tokenSemantic tokenValueColourbackgroundsgds/bg-transparentTransparenthover-bgsgds/bg-transparent + sgds/bg-translucent-fixed-darkTransparent + oklch(from #0E0E0E l c h / 0.2)text-and-icon-colorsgds/color-fixed-light#F3F3F3

Usage

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

Best practices

Primary action
Use a clear action label

Specific button labels help users understand the outcome before they act.

Click here
Do not use vague labels

Generic labels such as 'Click here' or 'Submit' without context slow users down.

Accessibility considerations

Built-in accessibility

  • Buttons render as native buttons by default and anchors when `href` is provided.
  • The component exposes disabled and 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 disabled button as the only way to explain what users need to do next.

Keyboard interaction

KeyInteractionTabMoves focus from the button to the next focusable element.Shift+TabMoves focus to the previous interactive element.EnterActivates the focused button.SpaceActivates the focused button.

Updates

DateVersionDescriptionLoading updates…

Roadmap

Planned itemStatusTargetFuture enhancements for buttonPlannedTBD

Feedback

Have suggestions or feedback?

Share them with us on Slack → #design-system-feedback

Bug Reports

Found a bug or issue?

Report it on GitHub Issues → sgds/components/button

Singapore Government Design System

The Singapore Government Design System was developed to empower teams in creating fast, accessible and mobile-friendly digital services.