Default

IconButtons are composed of the Button component with some slight differences in defaults and a few additional props. IconButton accepts all the same props as Button, with the addition of a specific icon and tooltip props. Unlike Button, IconButton's default type is ButtonType.Tertiary as this is the most common type for IconButtons.

⚛️ For a full description available props and variants inherited from the Button component, check out the Button doc.

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

Best practices

1. Avoid mixing and matching IconButton types that are adjacent to each other. Stick to the same type for a set of related actions.
2. A tooltip isn't necessary for universally understood icons such as x to close, but in these cases an aria-label is needed.

Types

Use the default ButtonType.Tertiary in most cases. For specific more important actions, ButtonType.Secondary can be used (often combined with isRound for standalone actions).

<IconButton icon={<Team />} tooltip={{ content: "Tertiary (Default)" }} />
<IconButton type={ButtonType.Secondary} icon={<Team />} tooltip={{ content: "Secondary" }} />

Tooltip

IconButton includes an optional tooltip that's baked right in, no need to wrap it in a <Tooltip />. To use a tooltip, pass any tooltip props such as content, position etc to the tooltip prop. The tooltip prop accepts any prop that the Tooltip component supports.

<IconButton
  icon={<Team />}
  tooltip={{
    content: "Tooltip content",
    position: TooltipPosition.Bottom,
    size: TooltipSize.Large,
  }}
/>

Sizes

Just like Button, IconButton accepts the ButtonSize enum to control its size. By default, IconButton uses the medium size.

<IconButton type={ButtonType.Secondary} size={ButtonSize.Large} icon={<Team />} tooltip={{ content: "Large" }} aria-label="Large" />
<IconButton type={ButtonType.Secondary} size={ButtonSize.Medium} icon={<Team />} tooltip={{ content: "Medium" }} aria-label="Medium" />
<IconButton type={ButtonType.Secondary} size={ButtonSize.Small} icon={<Team />} tooltip={{ content: "Small" }} aria-label="Small" />
<IconButton type={ButtonType.Secondary} size={ButtonSize.XSmall} icon={<Team size={IconSize.Small} />} tooltip={{ content: "XSmall" }} aria-label="Extra small" />

Rounded

Use the isRound prop for standalone buttons that aren't part of a set. This is most commonly used for add/create buttons which aren't commonly rendered as part of a group of buttons.

<IconButton isRound type={ButtonType.Secondary} icon={<Add />} tooltip={{ content: "Create folder" }} />

Animation

IconButton can animate between two icons. Just give each icon a unique key and conditionally render them in the icon prop

() => {
  const [editing, setEditing] = React.useState(false);

  return (
    <IconButton
      onClick={() => setEditing(!editing)}
      icon={editing ? <Tick key="edit" /> : <Edit key="tick" />}
      aria-label="Edit"
      aria-pressed={editing}
    />
  );
}

Accessibility

1. Always provide text to describe an icon button. Typically this is done with the tooltip prop, which accepts all of the props for a Tooltip. If a tooltip is not needed or provided, use an aria-label to describe the action for screen readers.