IconButton

View source on GitHub

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.

Props

Component 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.
`tooltip`	`{\| text: string, accessibilityLabel?: string, inline?: boolean, idealDirection?: "up" \| "right" \| "down" \| "left", zIndex?: Indexable, \|}`	-
	Adds a Tooltip on hover/focus of the IconButton. See the With Tooltip variant to learn more.

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.
`type`	`"submit" \| "button"`	`"button"`
	Use "submit" if IconButton is used within or associated with a form.

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

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.

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.

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

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: "Create Pin menu". The label should describe the intent of the action, not the Icon itself. For example, use "Edit board" instead of "Pencil".

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.

function Example() {
  const [open, setOpen] = React.useState(false);
  const [selected, setSelected] = React.useState([]);
  const anchorRef = React.useRef(null);
  const onSelect = ({ item }) => {
    if (selected.some(({ value }) => value === item.value)) {
      setSelected((selected) => selected.filter(({ value }) => value != item.value));
    } else {
      setSelected((selected) => [...selected, item]);
    }
  };

  return (
    <Flex justifyContent="center">
      <IconButton
        accessibilityControls="accessibility-example"
        accessibilityExpanded={open}
        accessibilityHaspopup
        accessibilityLabel="Create Pin Menu"
        bgColor="lightGray"
        icon="add"
        iconColor="darkGray"
        onClick={() => setOpen((prevVal) => !prevVal)}
        ref={anchorRef}
        selected={open}
        size="lg"
        tooltip={{text: "Create Pin", idealDirection: "up"}}
      />
      {open && (
        <Dropdown
          anchor={anchorRef.current}
          id="accessibility-example"
          onDismiss={() => setOpen(false)}
        >
          <Dropdown.Section label="Create">
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Pin', label: 'Pin' }}
              selected={selected}
            />
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Story Pin', label: 'Story Pin' }}
              selected={selected}
            />
          </Dropdown.Section>
        </Dropdown>
      )}
    </Flex>
  );
}

function Example() {
  const [open, setOpen] = React.useState(false);
  const [selected, setSelected] = React.useState([]);
  const anchorRef = React.useRef(null);
  const onSelect = ({ item }) => {
    if (selected.some(({ value }) => value === item.value)) {
      setSelected((selected) => selected.filter(({ value }) => value != item.value));
    } else {
      setSelected((selected) => [...selected, item]);
    }
  };

  return (
    <Flex justifyContent="center">
      <IconButton
        accessibilityControls="accessibility-example"
        accessibilityExpanded={open}
        accessibilityHaspopup
        accessibilityLabel="Create Pin Menu"
        bgColor="lightGray"
        icon="add"
        iconColor="darkGray"
        onClick={() => setOpen((prevVal) => !prevVal)}
        ref={anchorRef}
        selected={open}
        size="lg"
        tooltip={{text: "Create Pin", idealDirection: "up"}}
      />
      {open && (
        <Dropdown
          anchor={anchorRef.current}
          id="accessibility-example"
          onDismiss={() => setOpen(false)}
        >
          <Dropdown.Section label="Create">
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Pin', label: 'Pin' }}
              selected={selected}
            />
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Story Pin', label: 'Story Pin' }}
              selected={selected}
            />
          </Dropdown.Section>
        </Dropdown>
      )}
    </Flex>
  );
}

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.

function Example(props) {
  return (
    <Flex gap={2}>
      <Avatar name="James Jones" src="https://i.ibb.co/2Fc00R3/james.jpg" size="md" />
      <Flex gap={2} alignItems="center">
        <Text inline weight="bold">
          <Link
            accessibilityLabel="Open the settings page"
            target="blank"
            inline
            href="https://www.pinterest.com/settings/"
          >
            James Jones
          </Link>
        </Text>
        <IconButton
          accessibilityLabel="Open the settings page"
          href="https://www.pinterest.com/settings/"
          icon="edit"
          role="link"
          size="xs"
          tabIndex="-1"
          target="blank"
          tooltip={{text: "Edit name"}}
        />
      </Flex>
    </Flex>
  );
}

function Example(props) {
  return (
    <Flex gap={2}>
      <Avatar name="James Jones" src="https://i.ibb.co/2Fc00R3/james.jpg" size="md" />
      <Flex gap={2} alignItems="center">
        <Text inline weight="bold">
          <Link
            accessibilityLabel="Open the settings page"
            target="blank"
            inline
            href="https://www.pinterest.com/settings/"
          >
            James Jones
          </Link>
        </Text>
        <IconButton
          accessibilityLabel="Open the settings page"
          href="https://www.pinterest.com/settings/"
          icon="edit"
          role="link"
          size="xs"
          tabIndex="-1"
          target="blank"
          tooltip={{text: "Edit name"}}
        />
      </Flex>
    </Flex>
  );
}

Localization

Be sure to localize accessibilityLabel.

Variants

Role

IconButton can be use for navigation or actions.

<IconButton
  accessibilityLabel="This IconButton is an example of IconButton acting as a link"
  icon="visit"
  role="link"
  target="blank"
  href="https://www.pinterest.com"
  tooltip={{text: "Link example"}}
/>

<IconButton
  accessibilityLabel="This IconButton is an example of IconButton acting as a link"
  icon="visit"
  role="link"
  target="blank"
  href="https://www.pinterest.com"
  tooltip={{text: "Link example"}}
/>

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.

<IconButton
  accessibilityLabel="This IconButton is an example of IconButton acting as a button"
  icon="share"
  onClick={() => {}}
  tooltip={{text: "Button Example"}}
/>

<IconButton
  accessibilityLabel="This IconButton is an example of IconButton acting as a button"
  icon="share"
  onClick={() => {}}
  tooltip={{text: "Button Example"}}
/>

role = button

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

Size

IconButton is available in 5 fixed sizes:

xl (56px)
Extra large IconButtons should be used sparingly and only in places where the UI has a case for an extra-large IconButton.
lg (48px)
Large is the only size that should be used on Pinner surfaces.
md (40px)
Medium is the size used on more dense UI such as business surfaces or internal tools.
sm (32px)
Small IconButton should be used sparingly and only in places where the UI is very dense.
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="xl"

size="lg"

size="md"

size="sm"

size="xs"

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

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

iconColor="red"

iconColor="darkGray"

iconColor="gray"

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

Red ("red"). High emphasis, used for primary actions.
Light Gray ("lightGray"). Medium emphasis, used for secondary actions.
Transparent Dark Gray ("transparentDarkGray"). Medium emphasis, used for secondary actions, usually above a colored background.
Gray ("gray"). Used for tertiary actions or in cases where the primary "red" is not an option. Medium emphasis when placed on dark backgrounds, used for secondary actions.
White ("white"). Used when there is a need of an IconButton over an image or colored background to provide better contrast and visibility.
Transparent ("transparent"). Used when there is a need to have an IconButton over an image without a background.
Dark Gray ("darkGray"). Used as the selected state for IconButton.

bgColor="red"

bgColor="lightGray"

bgColor="transparentDarkGray"

bgColor="gray"

bgColor="white"

bgColor="transparent"

bgColor="darkGray"

By specifying the tooltip property, a Tooltip will automatically be triggered when IconButton is hovered or focused. If the Tooltip text does not provide more information than the IconButton accessibilityLabel, set the tooltip prop's accessibilityLabel to an empty string, as seen below in the Edit example.

<Flex gap={4}>
  <IconButton
    accessibilityLabel="Sharing"
    icon="share"
    tooltip={{
      text: "This Pin is private unless you share it with others.",
      idealDirection: "up"
    }}
  />
  <IconButton
    accessibilityLabel="Edit"
    icon="edit"
    tooltip={{
      text: "Edit",
      accessibilityLabel: "",
      idealDirection: "up"
    }}
  />
</Flex>

<Flex gap={4}>
  <IconButton
    accessibilityLabel="Sharing"
    icon="share"
    tooltip={{
      text: "This Pin is private unless you share it with others.",
      idealDirection: "up"
    }}
  />
  <IconButton
    accessibilityLabel="Edit"
    icon="edit"
    tooltip={{
      text: "Edit",
      accessibilityLabel: "",
      idealDirection: "up"
    }}
  />
</Flex>

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.

<IconButton
  accessibilityLabel="Go to next steps"
  icon="directional-arrow-right"
  tooltip={{text: "Built-in Gestalt Icon"}}
/>

<IconButton
  accessibilityLabel="Go to next steps"
  icon="directional-arrow-right"
  tooltip={{text: "Built-in Gestalt Icon"}}
/>

<IconButton
  accessibilityLabel="Go to next steps"
  dangerouslySetSvgPath={{ __path: 'M23 5v14a4 4 0 0 1-4 4H5a4 4 0 0 1-4-4v-5.5h10.258l-1.94 1.939a1.5 1.5 0 0 0 2.121 2.122L17 12l-5.561-5.561a1.501 1.501 0 0 0-2.121 2.122l1.94 1.939H1V5a4 4 0 0 1 4-4h14a4 4 0 0 1 4 4'}}
  tooltip={{text: "Custom Icon"}}
/>

<IconButton
  accessibilityLabel="Go to next steps"
  dangerouslySetSvgPath={{ __path: 'M23 5v14a4 4 0 0 1-4 4H5a4 4 0 0 1-4-4v-5.5h10.258l-1.94 1.939a1.5 1.5 0 0 0 2.121 2.122L17 12l-5.561-5.561a1.501 1.501 0 0 0-2.121 2.122l1.94 1.939H1V5a4 4 0 0 1 4-4h14a4 4 0 0 1 4 4'}}
  tooltip={{text: "Custom Icon"}}
/>

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.

function SectionsIconButtonDropdownExample() {
  const [open, setOpen] = React.useState(false);
  const [selected, setSelected] = React.useState([]);
  const anchorRef = React.useRef(null);
  const onSelect = ({ item }) => {
    if (selected.some(({ value }) => value === item.value )) {
      setSelected((selected) => selected.filter(({ value }) => value != item.value));
    } else {
      setSelected((selected) => [...selected, item]);
    }
  };

  return (
    <Flex justifyContent="center">
      <IconButton
        accessibilityControls="sections-dropdown-example"
        accessibilityExpanded={open}
        accessibilityHaspopup
        accessibilityLabel="Create Pin Menu"
        bgColor="lightGray"
        icon="add"
        iconColor="darkGray"
        onClick={() => setOpen((prevVal) => !prevVal)}
        ref={anchorRef}
        selected={open}
        size="lg"
        tooltip={{text: "Create", accessibilityLabel: "", idealDirection: "up"}}
      />
      {open && (
        <Dropdown anchor={anchorRef.current} id="sections-dropdown-example" onDismiss={() => setOpen(false)}>
          <Dropdown.Section label="Create">
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Pin', label: 'Pin' }}
              selected={selected}
            />
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Story Pin', label: 'Story Pin' }}
              selected={selected}
            />
          </Dropdown.Section>
          <Dropdown.Section label="Add">
            <Dropdown.Item
              badge={{ text: 'New' }}
              onSelect={onSelect}
              option={{ value: 'Note', label: 'Note' }}
              selected={selected}
            />
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Section', label: 'Section' }}
              selected={selected}
            />
          </Dropdown.Section>
        </Dropdown>
      )}
    </Flex>
  );
}

function SectionsIconButtonDropdownExample() {
  const [open, setOpen] = React.useState(false);
  const [selected, setSelected] = React.useState([]);
  const anchorRef = React.useRef(null);
  const onSelect = ({ item }) => {
    if (selected.some(({ value }) => value === item.value )) {
      setSelected((selected) => selected.filter(({ value }) => value != item.value));
    } else {
      setSelected((selected) => [...selected, item]);
    }
  };

  return (
    <Flex justifyContent="center">
      <IconButton
        accessibilityControls="sections-dropdown-example"
        accessibilityExpanded={open}
        accessibilityHaspopup
        accessibilityLabel="Create Pin Menu"
        bgColor="lightGray"
        icon="add"
        iconColor="darkGray"
        onClick={() => setOpen((prevVal) => !prevVal)}
        ref={anchorRef}
        selected={open}
        size="lg"
        tooltip={{text: "Create", accessibilityLabel: "", idealDirection: "up"}}
      />
      {open && (
        <Dropdown anchor={anchorRef.current} id="sections-dropdown-example" onDismiss={() => setOpen(false)}>
          <Dropdown.Section label="Create">
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Pin', label: 'Pin' }}
              selected={selected}
            />
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Story Pin', label: 'Story Pin' }}
              selected={selected}
            />
          </Dropdown.Section>
          <Dropdown.Section label="Add">
            <Dropdown.Item
              badge={{ text: 'New' }}
              onSelect={onSelect}
              option={{ value: 'Note', label: 'Note' }}
              selected={selected}
            />
            <Dropdown.Item
              onSelect={onSelect}
              option={{ value: 'Section', label: 'Section' }}
              selected={selected}
            />
          </Dropdown.Section>
        </Dropdown>
      )}
    </Flex>
  );
}

Ref

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

function IconButtonPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const [checked, setChecked] = React.useState(false);
  const anchorRef = React.useRef(null);
  return (
    <React.Fragment>
      <IconButton
        accessibilityLabel="Favorite this Pin"
        bgColor="white"
        icon="heart"
        iconColor="red"
        onClick={() => { setOpen(true), setChecked(!checked) } }
        selected={checked}
        ref={anchorRef}
        tooltip={{text: "Favorite this pin", accessibilityLabel: ""}}
      />
      {open && checked &&(
        <Popover
          anchor={anchorRef.current}
          idealDirection="right"
          onDismiss={() => setOpen(false)}
          shouldFocus={false}
        >
          <Box padding={3}>
            <Text weight="bold">You loved this pin!</Text>
          </Box>
        </Popover>
      )}
    </React.Fragment>
  );
}

function IconButtonPopoverExample() {
  const [open, setOpen] = React.useState(false);
  const [checked, setChecked] = React.useState(false);
  const anchorRef = React.useRef(null);
  return (
    <React.Fragment>
      <IconButton
        accessibilityLabel="Favorite this Pin"
        bgColor="white"
        icon="heart"
        iconColor="red"
        onClick={() => { setOpen(true), setChecked(!checked) } }
        selected={checked}
        ref={anchorRef}
        tooltip={{text: "Favorite this pin", accessibilityLabel: ""}}
      />
      {open && checked &&(
        <Popover
          anchor={anchorRef.current}
          idealDirection="right"
          onDismiss={() => setOpen(false)}
          shouldFocus={false}
        >
          <Box padding={3}>
            <Text weight="bold">You loved this pin!</Text>
          </Box>
        </Popover>
      )}
    </React.Fragment>
  );
}

Writing

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

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.

Edit page on GitHub

IconButton

Props

Additional role="button" Props

Additional role="link" Props

Usage guidelines

Best practices

Accessibility

ARIA attributes

Keyboard interaction

Localization

Variants

Role

Size

Icon color

Background color

With Tooltip

Custom icon

Selected state

Ref

Writing

Related