Icon button
A square ghost button whose only content is a 16px line icon; it always carries an accessible name and, as a toggle, aria-pressed.
stable · light DOM · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
<j3w1-icon-button id="example-icon-button-default"><button class="icon-button" type="button" aria-label="Close panel">
<svg class="icon-button-icon" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M3.5 3.5l9 9M12.5 3.5l-9 9"></path></svg>
</button></j3w1-icon-button>toggle
<j3w1-icon-button id="example-icon-button-toggle"><button class="icon-button" type="button" aria-label="Pin window" aria-pressed="false">
<svg class="icon-button-icon" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="miter"><path d="M6 2h4v4l2 2v2H4V8l2-2z"></path><path d="M8 10v4"></path></svg>
</button></j3w1-icon-button>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@4.0.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/icon-button.css';
import '@j3w1/ui/register/icon-button';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy icon-button --out ./vendor/j3w1/icon-buttonThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
tone | CustomEvent | Button tone: primary, secondary, tertiary or destructive. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-action | CustomEvent | A native button activated. Prevent default on this event to cancel the associated native default action. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Icon button icon-button
A square ghost button whose only content is a 16px line icon; it always carries an accessible name and, as a toggle, aria-pressed.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.action.secondary.bgobserveduse | rgb(0 0 0 / 0%) | Secondary button has no fill. |
root.text | color.action.tertiary.textapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
root.bg-hover | color.action.tertiary.hover-bgobserveduse | #1c0a09 | Ghost and icon button hover. |
root.bg-active | color.interaction.pressed.bgobserveduse | #420f0c | Pressed fill. |
root.border-active | color.border.activeobserveduse | #e53935 | Active or focused control border. |
root.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
root.bg-toggled | color.interaction.selection.bgapproveduse | #531310 | Selected row, tab, workspace; D-027 recessed the fill, leaving the 2px indicator and the check to carry selection. |
root.text-toggled | color.interaction.selection.textobserveduse | #f4eeee | Text on the selection. |
root.border-toggled | color.border.selected-indicatorobserveduse | #e53935 | 2px indicator bar on the selected tab or nav item. |
root.ring-toggled | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
root.text-disabled | color.text.disabledapproveduse | #a3676b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
root.bg-disabled | color.interaction.disabled.bgapproveduse | #0d0707 | D-041 interaction.disabled.bg: color.primitive.modern.panel. |
root.border-disabled | color.border.disabledapproveduse | #482b2b | D-041 border.disabled: color.primitive.modern.divider. |
icon.stroke | color.icon.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
Purpose
The tertiary tone in a square, for toolbar actions, close and clear
affordances and boolean toggles such as pin, mute or wrap. If the label must
be visible, use button.
Anatomy
Parts as listed in the anatomy.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | color.action.tertiary.text icon, no fill; transparent 1px border | — |
| hover | background → color.action.tertiary.hover-bg | cursor: pointer; hover-capable pointers only |
| focus-visible | 1px dashed ring color.interaction.focus.ring at −2px | the ring |
| active | background → color.interaction.pressed.bg; border → color.border.active | border change; no translation |
| disabled | color.text.disabled on color.interaction.disabled.bg, 1px color.border.disabled; no hover | disabled; cursor: not-allowed |
| toggled | color.interaction.selection.bg fill, color.interaction.selection.text, border color.border.selected-indicator; filled icon form | aria-pressed="true"; the filled icon shape; the border |
| toggled+focus-visible | the selection fill and 1px dashed color.interaction.focus.ring at −2px | both visible at once |
Precedence: disabled > toggled > active > hover; focus-visible is always drawn.
Keyboard
Native; the toggle does not move focus. In a toolbar the host applies roving tabindex; the button binds nothing.
Accessibility
Every icon button has an accessible name (aria-label or aria-labelledby)
and a tooltip that repeats it but is not the name. The SVG is
aria-hidden="true" and focusable="false". The name never changes with
the state (“Mute”, not “Mute” / “Unmute”). The icon meets 4.5:1 and rings
3:1 on every fill. Target at least 24×24 CSS pixels in compact, with 4px
between neighbours.
Portability
Square, fill, border and outline; the currentColor icon follows every
state. A host without inline SVG uses its icon theme at 16px and records the
substitution; one without dashed outlines draws a solid 1px ring.
Non-examples
A circle. No accessible name. A toggle that changes its label instead of
aria-pressed. A hover that recolours only the icon. An emoji or icon-font
glyph instead of the SVG. A toggled state shown by colour alone with a line
icon. A shadow or scale on press.
Contrast report
13 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 1 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| icon-button default text | default | text | color.action.tertiary.text #e99499 | color.action.secondary.bg #000000 | 9.16 | 4.5 | pass |
| icon-button hover text | hover | text | color.action.tertiary.text #e99499 | color.action.tertiary.hover-bg #1c0a09 | 8.35 | 4.5 | pass |
| icon-button focus-visible text | focus-visible | text | color.action.tertiary.text #e99499 | color.action.secondary.bg #000000 | 9.16 | 4.5 | pass |
| icon-button focus-visible outline | focus-visible | ui | color.interaction.focus.ring #e53935 | color.action.secondary.bg #000000 | 4.97 | 3 | pass |
| icon-button active text | active | text | color.action.tertiary.text #e99499 | color.interaction.pressed.bg #420f0c | 7.02 | 4.5 | pass |
| icon-button active border | active | ui | color.border.active #e53935 | color.interaction.pressed.bg #420f0c | 3.81 | 3 | pass |
| icon-button toggled text | toggled | text | color.interaction.selection.text #f4eeee | color.interaction.selection.bg #531310 | 12.47 | 4.5 | pass |
| icon-button toggled+focus-visible text | toggled+focus-visible | text | color.interaction.selection.text #f4eeee | color.interaction.selection.bg #531310 | 12.47 | 4.5 | pass |
| icon-button toggled+focus-visible outline | toggled+focus-visible | ui | color.interaction.focus.ring #e53935 | color.interaction.selection.bg #531310 | 3.38 | 3 | pass |
| toggled border against the panel | toggled | ui | color.border.selected-indicator #e53935 | color.surface.default #0d0707 | 4.73 | 3 | pass |
| toggled fill against the panel (decorative) | toggled | ui | color.interaction.selection.bg #531310 | color.surface.default #0d0707 | 1.40 | 3 | waived: aria-pressed, the filled icon form and the 1px selected-indicator border carry the state; the fill is not the boundary |
| disabled icon (exempt; house floor 3:1) | disabled | ui | color.text.disabled #a3676b | color.interaction.disabled.bg #0d0707 | 4.48 | 3 | pass |
| disabled border (exempt) | disabled | ui | color.border.disabled #482b2b | color.interaction.disabled.bg #0d0707 | 1.58 | 1 | pass |
Keys
| Key | Action |
|---|---|
| Tab / Shift+Tab | Moves focus to and from the button. |
| Enter / Space | Activates; the toggle variant flips aria-pressed. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: button toolbar tooltip segmented-control
Stress fixtures: FX-320 FX-ZOOM-200 FX-RM FX-HC FX-TOUCH FX-DENSITY FX-STATE-MATRIX