import {IconButton} from '@primer/react-brand'Examples
Default
Custom icons
Pass an SVG element to use a custom icon.
Variants
IconButton inherits standard variants from Button and adds danger and invisible variants.
Sizes
Rounded
Use rounded for circular controls, such as a chat submit action.
In a ButtonGroup
Use variant="joined" to display related IconButton components.
In a toolbar
Use small icon buttons for familiar actions in compact toolbars.
In an ActionMenu
Use an icon button as the trigger when a familiar icon clearly communicates that contextual actions are available. The menu label also supplies the accessible name for the generated menu trigger.
Description
Use description to add supplementary information to the tooltip while keeping aria-label as the action name.
Delayed tooltip
Wrap IconButton in Tooltip with delay="long" when familiar controls appear in a dense group and immediate pointer tooltips would be distracting. Keyboard focus remains immediate.
Loading
Inactive
Inactive controls use the same muted style for every variant and retain focus and activation so they can explain why an action is unavailable. They render with aria-disabled="true" and must not perform their normal action.
Component props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
icon | Icon | ReactElement | true | Octicon component or custom SVG element rendered in the center of the button | |
aria-label | string | true | Required non-empty accessible action name and default tooltip label | |
variant | 'primary', 'secondary', 'subtle', 'danger', 'invisible' | 'secondary' | false | Button variants plus IconButton-only danger and invisible variations |
size | 'small', 'medium', 'large' | number | 'medium' | false | Named size or custom control dimensions in CSS pixels |
description | string | undefined | false | Supplementary tooltip description |
tooltipDirection | 'nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w' | 's' | false | Preferred tooltip direction |
inactive | boolean | false | false | Applies variant-independent muted styling while preserving input for required feedback |
loading | boolean | false | false | Replaces the icon with a loading indicator and blocks activation without removing focus |
loadingAnnouncement | string | 'Loading' | false | Polite live-region message announced while loading |
rounded | boolean | false | false | Renders the control with a fully circular shape |
disabled | boolean | false | false | Disables the control using Button’s native or polymorphic behavior |
as | React.ElementType | 'button' | false | Element rendered by Button; provide href when rendering an anchor |