Get startedFoundationsComponentsPatternsGuidelinesResourcesAI
This site is a work in progress as part of GovTech {build} hackathon. Content may be incomplete or subject to change.

Icon button

An icon button combines an icon and a button into a compact interactive control.

GitHubGitHub logocomponents/icon-button
StorybookStorybook logocomponents/icon-button
DesignUsageAccessibilityUpdates

Purpose

Action in minimal space

Icon buttons let you place interactive controls in tight areas — toolbars, table rows, compact headers — without needing a text label.

Always label for accessibility

Because there's no visible text, icon buttons require an accessible aria-label so screen reader users understand the action.

Consistent visual weight

Using the icon button component keeps icon-only actions styled and sized consistently across your product.

Anatomy

1

Button container

2

Icon

3

Interactive state

Configuration

Variants

Icon button variants control the visual weight of the control to suit different interface contexts.

The default filled variant is visually heavier. Use in toolbars or alongside other solid controls where the button needs to stand out.

Playground

BETA
Variants

Structure

Component tokens

Component tokens are specific to each component. Use the table title as the prefix: dimension-32 under sgds/icon-button means sgds/icon-button/dimension-32.

sgds/icon-button
CategoryComponent tokenSemantic tokenValueSizedimension-32sgds/dimension/32—dimension-40sgds/dimension/40—dimension-48sgds/dimension/4848pxdimension-56sgds/dimension/56—

Usage

When to use

  • Use this component to help users understand where they are and move confidently to the next place.
  • Use it when the navigation pattern matches the scale of the journey and the relationship between destinations.

When not to use

  • Do not use this component when the page does not need another layer of navigation.
  • Do not add vague, repetitive, or competing labels that make the path harder to understand.

Best practices

Keep destinations clear

Short, specific labels and a clear current state help users move through the interface with confidence.

Do not compete with the page structure

Repeated or unnecessary navigation patterns make it harder to understand where to go next.

Accessibility considerations

Built-in accessibility

  • Icon buttons render as native buttons by default and anchors when `href` is provided.
  • The component supports an `ariaLabel` for the accessible name.

Labels and content

  • Always provide an accessible label that describes the action.
  • Use the icon only as a visual shortcut for the action.

Focus and interaction

  • Keep icon buttons close to the content or item they affect.
  • Avoid using several identical icon buttons without unique accessible labels.

Keyboard interaction

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

Updates

DateVersionDescriptionLoading updates…

Roadmap

Planned itemStatusTargetFuture enhancements for icon 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/icon-button

Singapore Government Design System

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