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.
<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
<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 witharia-labeloraria-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
disabledfor unavailable actions andaria-pressedfor 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.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--icon-button-color | var(--text-color) | Icon color for outline and text variants. | .icon-btn-outline / .icon-btn-text |
--icon-button-color-hover | var(--text-color) | Icon color on hover for text buttons. | .icon-btn-outline / .icon-btn-text |
--icon-button-color-active | var(--text-color) | Icon color when pressed for text buttons. | .icon-btn-outline / .icon-btn-text |
--icon-button-on-color | var(--on-primary) | Icon color on filled surfaces. | .icon-btn-solid / .icon-btn-outline |
--icon-button-surface-color | var(--icon-button-color) | Filled background and border color. | .icon-btn-solid / .icon-btn-outline |
--icon-button-surface-color-hover | var(--icon-button-color-hover) | Filled background and border color on hover. | .icon-btn-solid / .icon-btn-outline |
--icon-button-surface-color-active | var(--icon-button-color-active) | Filled background and border color when pressed. | .icon-btn-solid / .icon-btn-outline |
--icon-button-bg-color | transparent | Background of the base icon button. | .icon-btn |
--icon-button-border-color | transparent | Border of the base icon button. | .icon-btn |
--icon-button-highlight | var(--bg-highlight) | Background on hover and active text buttons. | .icon-btn |
--icon-button-border-width | var(--border-width) | Border thickness. | .icon-btn |
--icon-button-border-radius | 9999px | Corner radius. | .icon-btn |
--icon-button-size | 2.5rem | Width and height. | .icon-btn |
--icon-button-padding | var(--spacer-1) | Inner spacing. | .icon-btn |
--icon-button-svg-size | 1.125rem | Maximum width and height of the SVG icon. | .icon-btn |
--icon-button-disabled-text-color | var(--disabled-text-color) | Text color while disabled. | .icon-btn (disabled) |
--icon-button-disabled-bg-color | var(--disabled-bg-color) | Background color while disabled. | .icon-btn (disabled) |
--icon-button-disabled-border-color | var(--disabled-border-color) | Border color while disabled. | .icon-btn (disabled) |
--icon-button-focus-outline-width | var(--focus-outline-width) | Focus ring thickness. | .icon-btn (focus) |
--icon-button-focus-outline-style | var(--focus-outline-style) | Focus ring line style. | .icon-btn (focus) |
--icon-button-focus-outline-color | var(--focus-outline-color) | Focus ring color. | .icon-btn (focus) |
--icon-button-focus-outline-offset | var(--focus-offset) | Distance between the focus ring and control. | .icon-btn (focus) |
--icon-button-transition-duration | var(--transition-duration) | Duration of visual state transitions. | .icon-btn |
--icon-button-transition-easing | var(--transition-easing) | Timing curve for visual state transitions. | .icon-btn |