IconButton allows users to take actions and make choices with a single click or tap. IconButtons use icons instead of text to convey available actions on a screen. IconButton is typically found in forms, dialogs and toolbars. Some buttons are specialized for particular tasks, such as navigation or presenting menus.

IconButton Props

IconButton subcomponent props
Name
Type
Default
accessibilityLabel
Required
string
-

Label for screen readers to announce IconButton. See the Accessibility guidelines for details on proper usage.

bgColor
"transparent" | "darkGray" | "transparentDarkGray" | "gray" | "lightGray" | "white" | "red"
"transparent"

Primary colors to apply to the IconButton background. See background color variant to learn more.

dangerouslySetSvgPath
{| __path: string |}
-

Defines a new icon different from the built-in Gestalt icons. See custom icon variant to learn more.

disabled
boolean
-

When disabled, IconButton looks inactive and cannot be interacted with.

icon
$Keys<typeof icons>
-

Icon displayed in IconButton to convey the behavior of the component. Refer to the iconography guidelines regarding the available icon options.

iconColor
"darkGray" | "gray" | "red" | "white"
"gray"

Primary color to apply to the Icon. See icon color variant to learn more.

onClick
({| event: SyntheticMouseEvent<HTMLButtonElement> | SyntheticKeyboardEvent<HTMLButtonElement> | SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>, {| dangerouslyDisableOnNavigation: () => void |}> |}) => void
-

Callback fired when the component is clicked, pressed or tapped. See OnLinkNavigationProvider to learn more about link navigation.

padding
1 | 2 | 3 | 4 | 5
-

Sets a padding for the IconButton. See the size variant to learn more.

ref
HTMLButtonElement | HTMLAnchorElement
-

Forward the ref to the underlying button or anchor element. See the ref variant to learn more.

role
"button" | "link"
"button"

Defines the user interaction in the component. See the role variant to learn more.

size
"xs" | "sm" | "md" | "lg" | "xl"
"md"

The maximum height and width of IconButton. See the size variant to learn more.

tabIndex
-1 | 0
0

Removes IconButton from sequential keyboard navigation to improve accessibility. See the Accessibility guidelines for details on proper usage.

Additional role = button Props

Additional role = button subcomponent props
Name
Type
Default
accessibilityControls
string
-

Specifies the id of an associated element (or elements) whose contents or visibility are controlled by IconButton so that screen reader users can identify the relationship between elements. See the Accessibility guidelines for details on proper usage.

accessibilityExpanded
boolean
-

Indicates that IconButton hides or exposes collapsible components and expose whether they are currently expanded or collapsed. See the Accessibility guidelines for details on proper usage.

accessibilityHaspopup
boolean
-

Indicates that a component controls the appearance of interactive popup elements, such as menu or dialog. See the Accessibility guidelines for details on proper usage.

role
button
-

Sets button interaction in the component. See the role variant to learn more.

selected
boolean
-

Toggles between binary states: on/off, selected/unselected, open/closed. See the selected variant to learn more.

Additional role = link Props

Additional role = link subcomponent props
Name
Type
Default
href
Required
string
-

Specifies a link URL.

role
Required
link
-

Sets link interaction in the component. See the role variant and OnLinkNavigationProvider to learn more about link navigation.

rel
"none" | "nofollow"
-

Specifies the relationship between the current document and the linked document. See the role variant to learn more.

target
null | "self" | "blank"
-

Define the frame or window to open the anchor defined on href. See the role variant to learn more.

Usage guidelines

When to Use
  • Interface space is limited. Prioritize using a Button if space is available.
  • Triggering a Modal to complete a related task.
  • Creating visual separation of actions in text-heavy content.
  • Lower-emphasis actions that don't impede users from completing a task.
When Not to Use
  • Displaying icons that don't have actions associated with them. Use an Icon instead.
  • Displaying multiple IconButtons on a surface that uses the same icon for different actions.
  • Text is better suited to convey the action and/or the icon isn't quickly recognizable by users.
  • Destructive, high-emphasis actions, e.g "delete", "remove".

Best practices

Do

Use IconButton to perform low-emphasis actions, such as opening a Modal to edit a board.

Don't

Pair IconButton with a regular button to perform a high-emphasis action. IconButton should be a secondary action among regular buttons.

Do

Consider grouping multiple actions in an "ellipsis" IconButton to avoid distraction with an overload of icons.

Don't

Display more than 4 icon buttons in a single row as it can cause cognitive load and usability issues.

Do

Display a Tooltip in conjunction with IconButton to provide context when the icon alone would be insufficient to convey the purpose of the button.

Tropic greens: The taste of Petrol and Porcelain | Interior design, Vintage Sets and Unique Pieces agave
Don't

Add an IconButton on top of images unless it has a background that ensures easy readability and accessible contrast. Check the background color variant to learn more.

Accessibility

ARIA attributes

IconButton conveys the component behavior using iconography. IconButton requires accessibilityLabel, a text description for screen readers to announce and communicate the represented Icon. In the example below, the screen reader reads: "More Options."

If IconButton is used as a control button to show/hide a Popover-based component, we recommend passing the following ARIA attributes to assist screen readers:

  • accessibilityControls: informs the screen reader that IconButton controls the display of an anchored Popover-based component. It populates aria-controls.
  • accessibilityHaspopup: informs the screen reader that there’s a Popover-based component attached to IconButton. It populates aria-haspopup.
  • accessibilityExpanded: informs the screen reader whether an anchored Popover-based component is currently open or closed. It populates aria-expanded.

Keyboard interaction

The default behaviour for IconButton is to be focusable in sequential keyboard navigation in the order defined by the document's source order.

Use tabIndex to remove IconButton from the sequential keyboard navigation to improve accessibility. The example below shows a common use case when two consecutive and visually different elements perform the same action. One of them, in this case IconButton, can be removed from keyboard navigation to prevent screen readers from announcing the same interaction twice.
If IconButton is disabled, it's also unreachable from keyboard navigation.

Localization

Be sure to localize accessibilityLabel.

Variants

Role

IconButton can be use for navigation or actions.

role = link

If IconButton acts as a link, set role = link and pass role-specific props.

target is optional and defines the frame or window to open the anchor defined on href:

  • "null" opens the anchor in the same window.
  • "blank" opens the anchor in a new window.
  • "self" opens an anchor in the same frame.

rel is optional. Use "nofollow" for external links to specify to web crawlers not follow the link.

IconButtons that act as links can be paired with OnLinkNavigationProvider. See OnLinkNavigationProvider to learn more about link navigation.

role = button

If IconButton acts as a button, pass role-specific props.

Size

IconButton is available in 5 fixed sizes:

  1. xl (56px)
    Extra large IconButtons should be used sparingly and only in places where the UI has a case for an extra-large IconButton.
  2. lg (48px)
    Large is the only size that should be used on Pinner surfaces.
  3. md (40px)
    Medium is the size used on more dense UI such as business surfaces or internal tools.
  4. sm (32px)
    Small IconButton should be used sparingly and only in places where the UI is very dense.
  5. xs (24px)
    Use sparingly and only in places where the UI is very dense or has a case for an extra-small IconButton as they can be hard to see for people with visual impairments.

Use padding sparingly. The padding options are 1-5, which represents the padding in increments of 4 pixels (2 = 8px padding). Combine the padding with size options for custom icon/button size ratios. If omitted, padding is derived from the default padding for each size prop.

size="xs"
size="sm"
size="md"
size="lg"
size="xl"

Icon color

IconButton can be presented in combinations of icon and background colors. In the absence of combinations, for each iconColor or bgColor value, a default paired value is assigned.

Follow these guidelines for iconColor

  1. Red ("red"). High emphasis, used for primary actions.
  2. Dark Gray ("darkGray"). Medium emphasis, used for secondary actions.
  3. Light Gray ("lightGray"). Low emphasis when placed on white backgrounds, used for tertiary actions. Medium emphasis when placed on dark backgrounds, used for secondary actions.
  4. White ("white"). Used in a dark mode scheme or over a dark-colored background creating better visibility.
iconColor="darkGray"
iconColor="gray"
iconColor="red"
iconColor="white"

Background color

IconButton can be presented in combinations of icon and background colors. In the absence of combinations, for each iconColor or bgColor value, a default paired value is assigned.

Follow these guidelines for bgColor

  1. Red ("red"). High emphasis, used for primary actions.
  2. Dark Gray ("darkGray"). Medium emphasis, used for secondary actions.
  3. Transparent Dark Gray ("transparentDarkGray"). Medium emphasis, used for secondary actions, usually above a colored background.
  4. Light Gray ("lightGray"). Low emphasis when placed on white backgrounds, used for tertiary actions. Medium emphasis when placed on dark backgrounds, used for secondary actions.
  5. White ("white"). Used when there is a need of an IconButton over an image or colored background to provide better contrast and visibility.
  6. Transparent ("transparent"). Used when there is a need to have an IconButton over an image without a background.
bgColor="transparent"
bgColor="transparentDarkGray"
bgColor="darkGray"
bgColor="gray"
bgColor="lightGray"
bgColor="white"
bgColor="red"

Custom icon

IconButton accepts both Gestalt Icons and custom icons, as shown in the second example. For custom icons, follow our custom SVG icons guidelines.

Selected state

IconButton has a selected state to visually indicate that the element is selected, open, and/or active. If the selected state controls the display of a Popover-based component (open/closed), use accessibilityExpanded to inform screen reader users. See the Accessibility guidelines to learn more.

Ref

To control focus, or position any anchor components to IconButton, use ref, as shown in the example below.

Writing

When pairing IconButton with Tooltip, refer to the Tooltip component for writing guidelines.

Do
  • Use a descriptive label to describe the IconButton action by beginning with a verb.
Don't

Use the words "image" or "icon" in the description label; instead, prefer to use verbs that describe the action, e.g. "Save" or "Edit".

Button
Button allows users to take actions, and make choices using text labels to express what action will occur when the user interacts with it.

Icon
IconButtons use icons instead of text to convey available actions on a screen. Use an existing one from the Gestalt Icon library.

OnLinkNavigationProvider
OnLinkNavigationProvider allows external link navigation control across all children components with link behavior.

Dropdown
It's most common to anchor Dropdown to Button or IconButton.