Icon button

Compact, accessibly named actions.

When to use

Use an icon button for a familiar compact action when space is limited, such as closing a panel. Prefer a Button with visible text when the action may be unfamiliar.

Variants

Combine .icon-btn with a style and semantic color. Every button needs an accessible name. --action-color* controls primary text and outlines; --primary* controls solid surfaces.

HTML
<button class="icon-btn icon-btn-primary icon-btn-text" type="button" aria-label="Text action">
	<!-- Icon -->
</button>
<button class="icon-btn icon-btn-primary icon-btn-solid" type="button" aria-label="Solid action">
	<!-- Icon -->
</button>
<button
	class="icon-btn icon-btn-secondary icon-btn-outline"
	type="button"
	aria-label="Outline action">
	<!-- Icon -->
</button>

Sizes and state

HTML
<button
	class="icon-btn icon-btn-primary icon-btn-text icon-btn-sm"
	type="button"
	aria-label="Small action">
	<!-- Icon -->
</button>
<button
	class="icon-btn icon-btn-primary icon-btn-solid"
	type="button"
	aria-label="Disabled action"
	disabled>
	<!-- Icon -->
</button>

Accessibility and behavior

  • Use a native button with type="button" for commands. Provide a specific accessible name with aria-label or aria-labelledby.
  • Hide the decorative SVG from assistive technology so it does not duplicate the control name. A tooltip supplements the name rather than replacing it.
  • Keep Enter/Space activation and the focus indicator. Use native disabled for unavailable actions and aria-pressed for a toggle state managed by the application.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--icon-button-colorvar(--text-color)Icon color for outline and text variants..icon-btn-outline / .icon-btn-text
--icon-button-color-hovervar(--text-color)Icon color on hover for text buttons..icon-btn-outline / .icon-btn-text
--icon-button-color-activevar(--text-color)Icon color when pressed for text buttons..icon-btn-outline / .icon-btn-text
--icon-button-on-colorvar(--on-primary)Icon color on filled surfaces..icon-btn-solid / .icon-btn-outline
--icon-button-surface-colorvar(--icon-button-color)Filled background and border color..icon-btn-solid / .icon-btn-outline
--icon-button-surface-color-hovervar(--icon-button-color-hover)Filled background and border color on hover..icon-btn-solid / .icon-btn-outline
--icon-button-surface-color-activevar(--icon-button-color-active)Filled background and border color when pressed..icon-btn-solid / .icon-btn-outline
--icon-button-bg-colortransparentBackground of the base icon button..icon-btn
--icon-button-border-colortransparentBorder of the base icon button..icon-btn
--icon-button-highlightvar(--bg-highlight)Background on hover and active text buttons..icon-btn
--icon-button-border-widthvar(--border-width)Border thickness..icon-btn
--icon-button-border-radius9999pxCorner radius..icon-btn
--icon-button-size2.5remWidth and height..icon-btn
--icon-button-paddingvar(--spacer-1)Inner spacing..icon-btn
--icon-button-svg-size1.125remMaximum width and height of the SVG icon..icon-btn
--icon-button-disabled-text-colorvar(--disabled-text-color)Text color while disabled..icon-btn (disabled)
--icon-button-disabled-bg-colorvar(--disabled-bg-color)Background color while disabled..icon-btn (disabled)
--icon-button-disabled-border-colorvar(--disabled-border-color)Border color while disabled..icon-btn (disabled)
--icon-button-focus-outline-widthvar(--focus-outline-width)Focus ring thickness..icon-btn (focus)
--icon-button-focus-outline-stylevar(--focus-outline-style)Focus ring line style..icon-btn (focus)
--icon-button-focus-outline-colorvar(--focus-outline-color)Focus ring color..icon-btn (focus)
--icon-button-focus-outline-offsetvar(--focus-offset)Distance between the focus ring and control..icon-btn (focus)
--icon-button-transition-durationvar(--transition-duration)Duration of visual state transitions..icon-btn
--icon-button-transition-easingvar(--transition-easing)Timing curve for visual state transitions..icon-btn