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

Components

AccordionAlertBadgeBreadcrumbButtonCard groupCardIcon cardImage cardThumbnail cardCheckboxClose buttonCombo boxDatepickerDescription listDividerDrawerDropdownFile uploadFooterIcon buttonIcon listInputLinkMainnavMastheadModalOverflow menuPaginationProgress barQuantity toggleRadioSelectSidebarSidenavSkeletonSpinnerStepperSubnavSwitchSystem bannerTabTableTable of contentsTextareaToastTooltip

Icon button

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

GitHub
Storybook
DesignUsageAccessibilityUpdates

Purpose

Save space for actions

Use icon buttons in toolbars, table rows, and compact headers.

Label the action

Add an accessible label because the button has no visible text.

Keep icon actions consistent

The component keeps icon-only actions aligned, sized, and styled consistently.

Anatomy

1

Button container

2

Icon

Configuration

Variant

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 icon button needs to stand out.

Tone

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

The default tone. Use for standard icon-only actions in the main SGDS brand colour system.

Size

Icon button sizes let you match the control to the density of the surrounding layout.

The default size. Use for most icon-only actions across forms, dialogs, and general page content.

Disabled

Use the disabled state to prevent interaction when the action is not available in the current context.

The default. Icon buttons are interactive and respond to pointer and keyboard input.

Loading

Show a loading spinner inside the icon button while a triggered action is in progress.

The default state. The icon is shown and the button is interactive.

Active

Use active when an icon button represents a selected tool or toggled state.

Use for available actions that are not selected.

Structure

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.

CategoryTokenValueWhere it's usedSizesgds-dimension-4848pxHeight of the button; width of the button

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

Use icon buttons for actions that are universally recognised

Reserve icon-only buttons for widely understood actions: search, close, edit, and delete.

Do not use icon buttons for primary calls to action

Primary actions deserve a visible label. Use a regular button with text rather than an icon-only one.

Always provide an accessible label

Without visible text, icon buttons need an aria-label so screen reader users know what the action does.

Do not use misleading tones

Avoid styling destructive actions like neutral ones, or using danger tone for harmless actions.

Match the tone to the action

Use danger for destructive actions, neutral for quiet utility, and the brand default for everything else.

Do not crowd icon buttons together without separation

When icon buttons sit side by side, use the ghost variant or add spacing so users can tell them apart.

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

DateVersionDescription

Roadmap

Planned itemStatusTargetFuture enhancements for icon buttonPlannedTBD

Feedback

Have suggestions or feedback?

Share them with us on Slack → #ask-sgds-v3

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.

Past VersionsSGDS v1SGDS v2