<c-icon-button>
An icon-only button: a round native button that shows a single icon and takes its accessible name from an `aria-label` on the element.
Usage
Slot a c-icon into it, or pass an icon path in path for an icon drawn by
the button itself (the slot wins when both are given). Listen to the native
click event; a disabled or loading button does not deliver it.
<c-icon-button aria-label="Delete" variant="danger" @click="remove">
<c-icon :path="mdiDelete" />
</c-icon-button>
When to use
- A compact action whose icon is widely recognised: close, edit, delete, more actions, a toolbar control.
- When there is room for a visible label, prefer
c-buttonwith the icon in itsiconslot: a label is clearer than an icon alone. - For navigation, use
c-buttonwithhreforc-link; an icon button has nohref.
Appearances
appearance matches c-button's: filled (the default) for the main
action, then outlined, ghost (a light tint) and text (no fill) for lower
emphasis. The 3.x outlined, ghost and text boolean attributes still work
until 5.0; appearance wins when both are set. inverted is for a fixed dark
or brand-coloured backdrop: it paints the inverse-* family, which looks the
same in both theme modes.
Variants
variant matches c-button's and colours every appearance: primary (the
default), secondary, success, info, warning, or danger for a
destructive action. The filled success, info and warning buttons draw a dark
icon, which stays visible on their lighter fills; inverted, only the filled
look shows the colour. An app can change the default with
applyDefaults({ 'c-icon-button': { variant: 'secondary' } }); the icon
buttons the library draws inside its own components keep primary. The
danger attribute of earlier releases still works until 5.0; variant wins
when both are set.
Sizes
size is default (40px), small (32px) or x-small (28px). The slotted
icon is sized to match (24, 22 or 18px): a c-icon without size, or a
plain <svg> or <img>. A c-icon with its own size keeps it, for a
glyph that looks too small or too large at the button's size. An icon drawn
from path is always 24px.
Badge
badge shows a count in a bubble at the button's top-right corner. It is
hidden while the value is null or an empty string, so badge="0" still
shows 0. Put the count in the accessible name as well
(aria-label="3 notifications"): the label replaces the button's content,
bubble included.
Disabled and loading
disabled disables the native button: it leaves the tab order and ignores
the pointer. loading replaces the icon with a spinner and swallows clicks;
the button stays focusable and is announced as busy and unavailable
(aria-busy, aria-disabled). Mark the region the wait affects too, with
aria-busy or a live-region message.
Accessibility
The root part is a native <button>, so focus, keyboard activation and the
button role come from the platform. Its name comes from aria-label on the
c-icon-button element, which is forwarded to the inner button, as are the
other ARIA attributes (aria-expanded, aria-haspopup, …). Those holding
element ids (aria-controls, aria-describedby, …) give the button the
elements the ids name in your page. Without an aria-label the button is named only by
the text in its content, which is usually nothing or the badge count; visually
hidden slotted text also names it, and keeps naming it while loading.
The element's focus() focuses the inner button, as on a native button.
To show the name to sighted users too, put the button in a c-tooltip's
trigger slot. The tooltip text is announced as a description, so the
aria-label is still required.
Customization
Restyle via CSS parts: ::part(root) is the button, ::part(content) the
wrapper around the icon or spinner, and ::part(badge) the count bubble.
c-icon-button::part(badge) {
background-color: var(--c-error);
color: var(--c-on-error);
}
Examples
<template>
<div class="example-row">
<c-icon-button aria-label="Add">
<c-icon :path="mdiPlus" />
</c-icon-button>
<c-icon-button appearance="outlined" aria-label="Edit">
<c-icon :path="mdiPencil" />
</c-icon-button>
<c-icon-button appearance="ghost" aria-label="Like">
<c-icon :path="mdiHeart" />
</c-icon-button>
<c-icon-button appearance="text" aria-label="More actions">
<c-icon :path="mdiDotsVertical" />
</c-icon-button>
<c-icon-button aria-label="Delete" variant="danger">
<c-icon :path="mdiDelete" />
</c-icon-button>
<c-icon-button aria-label="3 notifications" badge="3">
<c-icon :path="mdiBellOutline" />
</c-icon-button>
<c-icon-button aria-label="Add" disabled>
<c-icon :path="mdiPlus" />
</c-icon-button>
</div>
</template>
<script setup lang="ts">
import {
mdiBellOutline,
mdiDelete,
mdiDotsVertical,
mdiHeart,
mdiPencil,
mdiPlus,
} from '@mdi/js';
</script>
<template>
<div class="example-row">
<c-icon-button aria-label="Search" size="x-small">
<c-icon :path="mdiMagnify" />
</c-icon-button>
<c-icon-button aria-label="Search" size="small">
<c-icon :path="mdiMagnify" />
</c-icon-button>
<c-icon-button aria-label="Search">
<c-icon :path="mdiMagnify" />
</c-icon-button>
</div>
</template>
<script setup lang="ts">
import { mdiMagnify } from '@mdi/js';
</script>
<template>
<div class="example-grid">
<div class="example-row">
<c-icon-button aria-label="Add">
<c-icon :path="mdiPlus" />
</c-icon-button>
<c-icon-button aria-label="Favourite" variant="secondary">
<c-icon :path="mdiStarOutline" />
</c-icon-button>
<c-icon-button aria-label="Approve" variant="success">
<c-icon :path="mdiCheck" />
</c-icon-button>
<c-icon-button aria-label="Details" variant="info">
<c-icon :path="mdiInformationOutline" />
</c-icon-button>
<c-icon-button aria-label="Warnings" variant="warning">
<c-icon :path="mdiAlertOutline" />
</c-icon-button>
<c-icon-button aria-label="Delete" variant="danger">
<c-icon :path="mdiDelete" />
</c-icon-button>
</div>
<div class="example-row">
<c-icon-button appearance="outlined" aria-label="Add">
<c-icon :path="mdiPlus" />
</c-icon-button>
<c-icon-button
appearance="outlined"
aria-label="Favourite"
variant="secondary"
>
<c-icon :path="mdiStarOutline" />
</c-icon-button>
<c-icon-button
appearance="outlined"
aria-label="Approve"
variant="success"
>
<c-icon :path="mdiCheck" />
</c-icon-button>
<c-icon-button appearance="outlined" aria-label="Details" variant="info">
<c-icon :path="mdiInformationOutline" />
</c-icon-button>
<c-icon-button
appearance="outlined"
aria-label="Warnings"
variant="warning"
>
<c-icon :path="mdiAlertOutline" />
</c-icon-button>
<c-icon-button appearance="outlined" aria-label="Delete" variant="danger">
<c-icon :path="mdiDelete" />
</c-icon-button>
</div>
<div class="example-row">
<c-icon-button appearance="ghost" aria-label="Add">
<c-icon :path="mdiPlus" />
</c-icon-button>
<c-icon-button
appearance="ghost"
aria-label="Favourite"
variant="secondary"
>
<c-icon :path="mdiStarOutline" />
</c-icon-button>
<c-icon-button appearance="ghost" aria-label="Approve" variant="success">
<c-icon :path="mdiCheck" />
</c-icon-button>
<c-icon-button appearance="ghost" aria-label="Details" variant="info">
<c-icon :path="mdiInformationOutline" />
</c-icon-button>
<c-icon-button appearance="ghost" aria-label="Warnings" variant="warning">
<c-icon :path="mdiAlertOutline" />
</c-icon-button>
<c-icon-button appearance="ghost" aria-label="Delete" variant="danger">
<c-icon :path="mdiDelete" />
</c-icon-button>
</div>
<div class="example-row">
<c-icon-button appearance="text" aria-label="Add">
<c-icon :path="mdiPlus" />
</c-icon-button>
<c-icon-button
appearance="text"
aria-label="Favourite"
variant="secondary"
>
<c-icon :path="mdiStarOutline" />
</c-icon-button>
<c-icon-button appearance="text" aria-label="Approve" variant="success">
<c-icon :path="mdiCheck" />
</c-icon-button>
<c-icon-button appearance="text" aria-label="Details" variant="info">
<c-icon :path="mdiInformationOutline" />
</c-icon-button>
<c-icon-button appearance="text" aria-label="Warnings" variant="warning">
<c-icon :path="mdiAlertOutline" />
</c-icon-button>
<c-icon-button appearance="text" aria-label="Delete" variant="danger">
<c-icon :path="mdiDelete" />
</c-icon-button>
</div>
</div>
</template>
<script setup lang="ts">
import {
mdiAlertOutline,
mdiCheck,
mdiDelete,
mdiInformationOutline,
mdiPlus,
mdiStarOutline,
} from '@mdi/js';
</script>
API reference
<c-icon-button>
An icon-only button: a round native button that shows a single icon and takes its accessible name from an `aria-label` on the element.
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
appearance | appearance | CIconButtonAppearance | — | The button's look: `filled` (unless set) for the main action; `outlined` (a primary outline, no fill), `ghost` (a light primary tint) or `text` (no fill or outline) for lower emphasis. |
badge | badge | null | number | string | null | Count shown in a bubble at the button's top-right corner; hidden while `null` or empty, so `0` still shows. |
disabled | disabled | boolean | false | Disable the button: it leaves the Tab order and ignores the pointer. |
inverted | inverted | boolean | false | Inverted colours for a fixed dark or brand-coloured backdrop: the `inverse-*` family, the same in both theme modes. Combines with every appearance. |
loading | loading | boolean | false | Show a spinner in place of the icon and ignore clicks; the button stays focusable and is announced as busy and unavailable. |
path | path | string | '' | Icon path of an icon the button draws itself, always 24px; a slotted icon wins over it. |
size | size | CIconButtonSize | 'default' | Size of the button: `default` (40px), `small` (32px) or `x-small` (28px). |
variant | variant | CIconButtonVariant | 'primary' app default | The button's colour, in every appearance: `primary` unless set (or changed app-wide), `secondary`, `success`, `info`, `warning`, or `danger` for a destructive action. |
danger deprecated | danger | boolean | false | Deprecated. Use `variant="danger"`. Danger look for a destructive action: the error colour. |
ghost deprecated | ghost | boolean | false | Deprecated. Use `appearance="ghost"`. Ghost appearance: a light primary tint, for lower emphasis. |
outlined deprecated | outlined | boolean | false | Deprecated. Use `appearance="outlined"`. Outlined appearance: a primary outline with no fill, for lower emphasis. |
text deprecated | text | boolean | false | Deprecated. Use `appearance="text"`. Text appearance: no fill or outline, the lightest look. |
app default marks a prop you can set for every instance at once with applyDefaults() — an explicit attribute or property on an instance still wins.
Methods
| Method | Signature | Description |
|---|---|---|
focus | (options?: FocusOptions): void | Focus its button, as `focus()` does on a native button: the element renders no box of its own to take it. |
Slots
| Slot | Description |
|---|---|
default | The icon: a `c-icon` or an `<svg>`; it wins over `path` |
CSS parts
Style from outside with c-icon-button::part(name) — parts are the library's only styling customization API.
| Part | Description |
|---|---|
root | The native `<button>` element carrying the visual styling |
content | Inner wrapper around the slotted icon or loading spinner |
badge | The count bubble at the button's top-right corner, shown by `badge` |
Types
Importable from the package root: import type { … } from '@cscfi/csc-ui'
CIconButtonAppearance
How strongly an icon button reads: `filled` for the main action, then `outlined`, `ghost` and `text`, each lighter than the last — `c-button`'s appearances.
export type CIconButtonAppearance = 'filled' | 'ghost' | 'outlined' | 'text';CIconButtonSize
Size of the icon button. `small` and `x-small` render progressively more compact buttons; omitting the attribute renders the default size.
export type CIconButtonSize = 'default' | 'small' | 'x-small';CIconButtonVariant
The colour an icon button takes — `c-button`'s variants: `primary` (unless set) and `secondary`, the brand families, or a status colour — `success`, `info`, `warning` and `danger`, a destructive action in the error colour.
export type CIconButtonVariant =
| 'danger'
| 'info'
| 'primary'
| 'secondary'
| 'success'
| 'warning';