IconButton

ReactProps

Github Storybook Markdown Copy for LLM

Icon Buttons are clickable icon elements that are used to trigger actions.

Import

import { IconButton } from "@cfa/react-core";

Live Editor

Guidelines

When to use

• IconButton is for a single, recognizable action where a labeled Button would crowd the layout.

Do

• Pair every IconButton with an aria-label that names the action verb, not the icon shape.
• In a toolbar row, use the Secondary variant, the same size across the row, and label each button with a verb only, such as Bold, Italic, or Export.
• For an inline action beside text, use the Tertiary variant, small size, placed at the end of the line it modifies.
• For a card or row action such as dismiss or a menu trigger, use the Tertiary variant for low visual weight. Add a Tooltip with the action name on hover and focus.

Avoid

• Using IconButton without an aria-label. Screen readers will have nothing to announce.
• Using IconButton when a labeled Button fits. Visible text is more accessible than an icon plus a hover Tooltip.

Events

Event Handlers

Use onPress instead of onClick.

The IconButton is built with the onPress prop, similar to onClick, but supports all user interactions via mouse, keyboard, and touch. The onPressStart, onPressEnd, and onPressChange events are triggered when a user presses, releases, or changes the state of the IconButton.

These handlers receive a PressEvent with information on type of event and the target.

PressEvent Props

Property	Type	Description
type	'pressstart' | 'pressend' | 'pressup' | 'press'	The type of press event being fired.
pointerType	PointerType	The pointer type that triggered the press event.
target	Element	The target element of the press event.
shiftKey	boolean	Whether the shift keyboard modifier was held during the press event.
ctrlKey	boolean	Whether the ctrl keyboard modifier was held during the press event.
metaKey	boolean	Whether the meta keyboard modifier was held during the press event.
altKey	boolean	Whether the alt keyboard modifier was held during the press event.
x	number	X position relative to the target.
y	number	Y position relative to the target.

PressEvent Methods

Method	Description
continuePropagation(): void	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can allow propagation.

Examples

Variant

The variant prop defaults to variant="tertiary", with these additional options: "primary" | "secondary" | "destructive".

Disabled

For a disabled IconButton, use the isDisabled prop.

Size

The size prop allows for four sizes: "xs" | "sm" | "md" | "lg". Default is xs.

Icon buttons render as squares at the same height as their Button counterparts where sizes align (sm with Button sm, and so on). Requires @cfa/design-tokens-core with --ds-semantic-size-xs for the xs size.

Customizing appearance

IconButton exposes CSS custom properties for contextual styling. Set them on the button or a parent container:

Custom property	Description
--icon-button-content	Icon color
--icon-button-surface	Background color
--icon-button-surface-hover	Background on hover
--icon-button-surface-active	Background on press or pending
--icon-button-border	Border color (secondary variant)
--icon-button-border-hover	Border on hover (secondary variant)
--icon-button-border-active	Border on press or pending (secondary variant)

Icon color does not change on hover or press — only the surface updates.

Use --icon-button-content on knockout or dark surfaces instead of the removed color="white" prop:

.my-surface {
  --icon-button-content: var(--ds-semantic-color-content-knockout);
}

LinkIconButton

The LinkIconButton component provides the same styling as the IconButton component but renders as an anchor (<a>) element using React Aria’s Link component underneath. It’s ideal for navigation actions that should visually appear as icon buttons.

Import

import { LinkIconButton } from "@cfa/react-core";

Example

LinkIconButton vs IconButton

• Use LinkIconButton when the action navigates to a new page or URL
• Use IconButton when the action performs an operation but stays on the same page
• LinkIconButton accepts the same styling props as IconButton (variant, size, isDisabled)
• LinkIconButton accepts standard anchor attributes like href, target, and rel

Styling

The LinkIconButton component supports the same styling options as IconButton (variants, sizes) and the same --icon-button-* custom properties shown above.

Disabled

For a disabled LinkIconButton, use the isDisabled prop.

Accessibility

Because LinkIconButton renders an icon without visible text, provide an accessible name with aria-label or aria-labelledby.