Components / Controls

IconButton

A square Button with only an icon. It needs a label, which is both its accessible name and its tooltip.

Source Edit this page

Default

When to use

Toolbar and table-row actions where the icon is widely understood (copy, close, delete).
Dense chrome where a text button would not fit.

Use something else when:

the action is not obvious from an icon alone: Button with visible text
it navigates: Link

Usage

tsx

import { IconButton } from "@arshad-shah/cynosure";
import { copy, trash } from "@arshad-shah/cynosure/icons";

<IconButton icon={copy} label="Copy document" onClick={copyDoc} />
<IconButton icon={trash} label="Delete" tone="danger" tooltipPlacement="bottom" />

Tone and variant

IconButton accepts the Button props variant, tone, size, loading, pressed, disabled and type, except children, iconEnd and fullWidth.

size="xs" is a 20px square with a smaller icon, for dense toolbars; it is still 24px to press (44px on coarse pointers).

Props

Every prop of IconButton
Prop	What it does	Type	Default
`icon`Required	The Facet icon shown in the button.	`IconData`
`label`Required	Required accessible name, also shown as the tooltip.	`string`
`tooltipPlacement`	Where the label tooltip appears.	`Placement`
`flipRtl`	The icon points along the reading direction (previous, next, back): it is mirrored in right-to-left text, as Icon's `flipRtl`. Default false.	`boolean`	`false`
`iconColor`	Any CSS colour for the icon, as Icon's `color` (e.g. a status the button shows for a moment). Default: the button's text colour.	`string`	`the button's text colour`
`wrapperClassName`	Added to the element around the button (the tooltip's anchor, the box the parent lays out), for layout: a grid area, `flex`, margins. `className` goes on the button itself.	`string`
`className`	Added to the button (or link) element, for layout.	`string`
`style`	Layout only. Restyle through `--cy-button-*` tokens.	`CSSProperties`
`color`	A one-off colour (any CSS colour), for a brand button such as "Get it on Google Play". Overrides `tone`. The text on a solid fill is white or black, whichever reads; on the other variants the colour is darkened or lightened until it reads on the surface. Prefer a tone or the theme's accent.	`string`
`type`	Defaults to "button" so a Cynosure button never submits a form by accident.	`"button" \| "submit" \| "reset"`	`"button"`
`aria-current`	Marks the button or link as the current item of a set: `"page"` for the page being shown (a link to it in a navigation bar or in Pagination), or `"step"`, `"location"`, `"date"`, `"time"` or `true`. Set on the button or link element. Default: not set.	`boolean \| "false" \| "true" \| "page" \| "step" \| "location" \| "date" \| "time"`	`not set`
`pressed`	Toggle state; mirrored to aria-pressed and data-pressed.	`boolean`
`tone`	Semantic colour.	`Tone`
`size`	Height and text size of the button. Default "md". `xs` (about 20px) is for dense desktop chrome: it looks small and is still 24px to press (44px on coarse pointers).	`DenseSize`	`"md"`
`variant`	Fill style.	`ButtonVariant`
`loading`	Shows LoadingDots, sets aria-busy and ignores activation while keeping the button's width.	`boolean`
`href`	A link that looks like a button (it navigates: a real `<a>`, so it opens in a new tab, can be copied, and so on). Only safe URLs are linked. The forwarded ref is not attached to a link (use `linkRef`). A link takes `target`, `id`, `aria-label`, `aria-current`, `className`, `style`, `data-testid` and `onClick`; the other button attributes do not apply to it.	`string`
`target`	With `href`: where it opens, e.g. `_blank`.	`string`
`linkRef`	With `href`: receives the link element (the forwarded ref is for the button element).	`Ref<HTMLAnchorElement>`
`confirm`	Ask before acting, in place: the first press arms the button and shows this text ("Press again to delete"), a second press within 4 seconds acts. Escape, leaving the button or the time running out disarms it.	`ReactNode`
`keepFocus`	A pointer press leaves focus where it was (an on-screen keypad beside a field keeps the field's caret). Keyboard users still reach it with Tab.	`boolean`
`data-testid`	Set on the button (or link) element, to find it in tests.	`string`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Behaviour and accessibility

Behaviour and accessibility, table 1
Input	Result
Click, tap, `EnterEnter`, `SpaceSpace`	Activates
Hover or keyboard focus	Shows the `label` tooltip
`EscEscape`, blur, pointer leave	Closes the tooltip

Name: label is set as aria-label. There is no native title tooltip.
Tooltip placement: tooltipPlacement defaults to top.
Current item: aria-current (for example "page") is set on the element, whether it is a button or, with href, a link.
Everything else works as in Button: type defaults to button.

Theming

IconButton uses the Button tokens, such as --cy-button-height-{sm,md,lg} and --cy-button-radius.

createTheme({ components: { button: { radius: "999px" } } });

className and style are for layout only.

Button · Tooltip · Toolbar

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

Tone and variantLink to "Tone and variant"

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

ThemingLink to "Theming"