Components Icon button

Icon button

Compact icon-only button for inline affordances — edit pencils on detail cards, X close on modal headers, dropdown triggers on tables. Two semantic colours: Neutral (the default for non-destructive actions) and Danger (for delete / archive / cancel).

Canonical

<button koala-icon-button="Neutral" aria-label="Edit">
    <koala-icon name="Pencil" />
</button>

Pair every icon button with aria-label — the icon alone doesn't tell screen readers what the button does.

Colours

2 colours

Neutral

koala-icon-button="Neutral"

Danger

koala-icon-button="Danger"

<button koala-icon-button="Danger" aria-label="Delete">
    <koala-icon name="Trash" />
</button>

Variants

2 variants

Outlined (default)

resting border + surface fill

Ghost

koala-icon-button-variant="Ghost"

<button koala-icon-button="Neutral" koala-icon-button-variant="Ghost" aria-label="Edit">
    <koala-icon name="Pencil" />
</button>

Ghost drops the resting border + fill — no chrome until hover. Use it in quiet contexts like the top nav, where a resting outline reads too heavy.

States

4 states

Default

Hover

Hover it — icon darkens, fill dims

Hover (Danger)

Hover it — danger text on danger-container

Focus

Tab to it — 2px primary focus ring

The resting icon is muted; hover and focus reveal the intent colour. There's no disabled treatment — an icon button is a contextual affordance, so omit it when the action isn't available rather than rendering it inert.

Props

2 attributes

Attribute	Values	Notes
koala-icon-button	Neutral, Danger	Colour. Defaults to Neutral. Targets both `<button>` and `<a>` elements.
koala-icon-button-variant	Outlined, Ghost	Defaults to Outlined (resting border + fill). Ghost has no resting chrome — hover-bg only, for quiet contexts like the top nav.

Do & don't

Do Always set aria-label. The visible icon doesn't read for screen readers.

Don't Don't use a full koala-btn with just an icon — the padding's wrong and the visual weight competes with the page's primary action.