IconButton

IconButton is used for buttons that show an icon in place of a text label.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Default

<IconButton icon={HeartIcon} aria-label="Favorite" />

<IconButton icon={HeartIcon} aria-label="Favorite" />

Style variants

The IconButton component ships with different variants that visually reinforce hierarchy or intent. This example just shows the 'primary' variant.

Button variants

<IconButton icon={HeartIcon} variant="primary" aria-label="Favorite" />

<IconButton icon={HeartIcon} variant="primary" aria-label="Favorite" />

Size variants

IconButtons can be rendered in different sizes. This example shows the 'small' size variant.

Button sizes

<IconButton icon={HeartIcon} size="small" aria-label="Favorite" />

<IconButton icon={HeartIcon} size="small" aria-label="Favorite" />

May be activated by a keyboard shortcut

<IconButton
  icon={InboxIcon}
  aria-label="Notifications"
  description="You have unread notifications"
  keyshortcuts="G+N"
/>

<IconButton
  icon={InboxIcon}
  aria-label="Notifications"
  description="You have unread notifications"
  keyshortcuts="G+N"
/>

Loading

Button loading state Loading pattern guidelines

<IconButton icon={HeartIcon} loading aria-label="Favorite" />

<IconButton icon={HeartIcon} loading aria-label="Favorite" />

Inactive

Button inactive state guidelines Degraded experiences pattern guidelines

<IconButton icon={HeartIcon} inactive aria-label="Favorite" />

<IconButton icon={HeartIcon} inactive aria-label="Favorite" />

More code examples

The previous examples are a curated subset of the full capabilities of the IconButton component. For more examples, see the IconButton Storybook stories.

Props

IconButton

Name	Required	Description
children	Required	`React.ReactNode` This will be the Button description.
variant		`'default' \| 'primary' \| 'danger' \| 'invisible' \| 'link'` Changes the look and feel of the button which is different for each variant
size		`'small' \| 'medium' \| 'large'` Changes the size of the icon button component
inactive		`boolean` Whether the button looks visually disabled, but can still accept all the same interactions as an enabled button.
icon		`Component` provide an octicon. It will be placed in the center of the button
aria-label		`string` Use an aria label to describe the functionality of the button. Please refer to [our guidance on alt text](https://primer.style/guides/accessibility/alternative-text-for-images) for tips on writing good alternative text.
keyshortcuts Deprecated		`string` Use `keybindingHint` instead.
keybindingHint		`string` Optional keybinding hint to show in the tooltip for this button. See the `KeybindingHint` component documentation for the correct format for this string. Has no effect if tooltip is overridden or disabled. Does not bind any keybindings for this button - this is only for visual hints.
tooltipDirection		`'n' \| 'ne' \| 'e' \| 'se' \| 's' \| 'sw' \| 'w' \| 'nw'` The direction of the tooltip.
description		`string` If `description` is provided, we will use a Tooltip to describe the button. Then `aria-label` is used to label the button.
sx		`SystemStyleObject`