CSC Design System v4
VueFlavour Vue React Angular TypeScriptPrimaryCSC UI ColorsPrimarySecondaryAccentCustom ColorsRedOrangeGreenBluePurplePink
Guides Getting started Customization Data visualization Migration guide Componentsc-accordionc-alertc-autocompletec-badgec-breadcrumbc-buttonc-button-groupc-cardc-checkboxc-color-pickerc-csc-logoc-data-tablec-date-pickerc-dividerc-file-uploadc-iconc-icon-buttonc-linkc-listc-loaderc-login-buttonsc-login-cardc-mainc-menuc-messagec-modalc-navigation-buttonc-number-fieldc-otp-inputc-pagec-paginationc-popoverc-progress-barc-progress-circlec-radio-groupc-selectc-side-navigationc-sliderc-spinnerc-statusc-stepsc-switchc-tablec-tabsc-tagsc-text-fieldc-time-pickerc-toastsc-toolbarc-tooltipc-tree-select

<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-button with the icon in its icon slot: a label is clearer than an icon alone.
  • For navigation, use c-button with href or c-link; an icon button has no href.

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

Basic
Vue React Angular TypeScript
<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>
Sizes
Vue React Angular TypeScript
<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>
Variants
Vue React Angular TypeScript
<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

PropertyAttributeTypeDefaultDescription
appearanceappearanceCIconButtonAppearance— 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.
badgebadgenull | number | stringnull Count shown in a bubble at the button's top-right corner; hidden while `null` or empty, so `0` still shows.
disableddisabledbooleanfalse Disable the button: it leaves the Tab order and ignores the pointer.
invertedinvertedbooleanfalse Inverted colours for a fixed dark or brand-coloured backdrop: the `inverse-*` family, the same in both theme modes. Combines with every appearance.
loadingloadingbooleanfalse Show a spinner in place of the icon and ignore clicks; the button stays focusable and is announced as busy and unavailable.
pathpathstring'' Icon path of an icon the button draws itself, always 24px; a slotted icon wins over it.
sizesizeCIconButtonSize'default' Size of the button: `default` (40px), `small` (32px) or `x-small` (28px).
variantvariantCIconButtonVariant'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 dangerbooleanfalse Deprecated. Use `variant="danger"`. Danger look for a destructive action: the error colour.
ghost deprecated ghostbooleanfalse Deprecated. Use `appearance="ghost"`. Ghost appearance: a light primary tint, for lower emphasis.
outlined deprecated outlinedbooleanfalse Deprecated. Use `appearance="outlined"`. Outlined appearance: a primary outline with no fill, for lower emphasis.
text deprecated textbooleanfalse 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

MethodSignatureDescription
focus(options?: FocusOptions): voidFocus its button, as `focus()` does on a native button: the element renders no box of its own to take it.

Slots

SlotDescription
defaultThe 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.

PartDescription
rootThe native `<button>` element carrying the visual styling
contentInner wrapper around the slotted icon or loading spinner
badgeThe 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';