Skip to content
design system
Thème d’affichage, actuellement Auto

atom · stable · since 2026-09

IconButton

Purpose

A button that shows a drawing and says a word. The product’s toolbars are full of them; an icon alone is a button with no name, the fault the product finds every day on other sites. Here the name is required, the drawing is hidden, and a toggle says its state.

When to use, when not

Use it in a toolbar, a table row or a header where the space is a square: close, menu, previous, next, settings. Do not use it for a page’s action (Button, with a verb), and never with an icon whose meaning is not universal: “Enregistrer” is a word, not a floppy disk.

Anatomy

  1. A square button or link, the size of a control.
  2. The drawing, from the icon set, hidden.
  3. The name, in aria-label.

Props

Props of IconButton
NameTypeDefaultWhat it does
labelstringThe name, French: what the button does ("Fermer", "Menu"). Read by assistive technology, never shown.
nameIconNameThe drawing, from the icon set.
size?'sm' | 'md' | 'lg''md'`sm` for a toolbar or a table row, `lg` for a page's one such control.
variant?'ghost' | 'secondary''ghost'`ghost` draws nothing until hovered; `secondary` has the control line.
pressed?boolean | undefinedA toggle: on or off, written as aria-pressed. Absent for a button that is not one.

Every other attribute of ButtonOrLinkAttributes passes through to the element.

States

Ghost, secondary, small, large, a toggle, a link, and unavailable.

asLink

With href the component renders a link; the name says the destination.

Light
Dark
320 px, light
320 px, dark
216 px, light
Forced colours, captured
IconButton, story asLink, as Chromium renders it with forced colours active

disabled

Light
Dark
320 px, light
320 px, dark
216 px, light
Forced colours, captured
IconButton, story disabled, as Chromium renders it with forced colours active

ghost

Nothing drawn until hovered; the name is in aria-label and the drawing is hidden.

Light
Dark
320 px, light
320 px, dark
216 px, light
Forced colours, captured
IconButton, story ghost, as Chromium renders it with forced colours active

large

Light
Dark
320 px, light
320 px, dark
216 px, light
Forced colours, captured
IconButton, story large, as Chromium renders it with forced colours active

secondary

Light
Dark
320 px, light
320 px, dark
216 px, light
Forced colours, captured
IconButton, story secondary, as Chromium renders it with forced colours active

small

Light
Dark
320 px, light
320 px, dark
216 px, light
Forced colours, captured
IconButton, story small, as Chromium renders it with forced colours active

toggle

aria-pressed written from the state: the button says whether the filter is on.

Light
Dark
320 px, light
320 px, dark
216 px, light
Forced colours, captured
IconButton, story toggle, as Chromium renders it with forced colours active

Accessibility contract

  • Role and name: a button or a link, named by label. A toggle carries aria-pressed.
  • Keyboard, focus: the browser’s; the ring is the system’s.
  • Live regions: none; a toggle announces its own state.
  • Pointer: the whole square is the target, at least the control size, above the pointer target floor.

Content rules

French. The name is what the button does, a verb or a noun the user knows (“Fermer”, “Menu”, “Page suivante”, “Paramètres”), never the icon’s name.

Do and don’t

  • Do write the name as the user would say it, not as the drawing is called.
  • Do use pressed only for a toggle, and leave it absent otherwise.
  • Do not rely on a title tooltip for the name.

Examples

<IconButton label="Fermer" name="close" onclick={close} />
<IconButton label="Filtrer les non-conformités" name="search" variant="secondary" pressed={filtered} onclick={toggle} />

Surfaces

  • App: the lab layout’s rail and drawer, the row menus; not ported yet.
  • Extension: the panel header and the wizard toolbar, when it is on Svelte.

Related

Button, Icon.

Decisions

  • 2026-09-24: label is required and not defaulted from the icon’s name: the icon’s name is not what the user needs to hear.

Criteria held by construction

  • 11.9, Dans chaque formulaire, l'intitulé de chaque bouton est-il pertinent ?
    The name is a required prop written to aria-label, so a button that shows only a drawing still says what it does.
  • 7.1, Chaque script est-il, si nécessaire, compatible avec les technologies d'assistance ?
    A toggle writes aria-pressed from its state at every render; a button that is not one carries no state.
  • 3.1, Dans chaque page web, l'information ne doit pas être donnée uniquement par la couleur. Cette règle est-elle respectée ?
    The pressed state is told by the fill and the line, and under forced colours by the system's highlight.

Tokens it reads

  • Colour: --rl-hover, --rl-ink, --rl-ink-soft, --rl-line-control, --rl-line-strong, --rl-sunken
  • Spacing: --rl-control-lg, --rl-control-md, --rl-control-sm
  • Layout: --rl-radius, --rl-border
  • Motion: --rl-duration-fast, --rl-ease

Seen in patterns