# Icon button

Enables users to control the visibility of other UI elements.

Tabs: [Guidelines](/components/web/icon-button/icon-button.guidelines.md) · [Code](/components/web/icon-button/icon-button.code.md)

## Features

- Comes in three visually different variants.

- Supports three sizes.

- Has a required Tooltip to ensure clarity around the button's function.

## When to use

At Pleo, we use Icon Buttons for actions that affect the visibility of other UI elements. Examples include closing a side panel, navigating between items in a side panel, and toggling the visiblity of filter controls. For more definitive actions, such as creating, editing, or deleting content, we prefer our regular [Button](/components/web/button/button.guidelines) component.

## Examples

### Variants

#### Primary

Use for important actions that affect the visibility of other UI elements.

```tsx
<IconButton variant={'primary'} tooltipProps={{content: 'Close'}} Icon={Close} />
```

#### Secondary

Use for actions of regular importance that affect the visibility of other UI elements.

```tsx
<IconButton variant={'secondary'} tooltipProps={{content: 'Close'}} Icon={Close} />
```

#### Quiet

Use for less important actions that affect the visibility of other UI elements.

```tsx
<IconButton variant={'quiet'} tooltipProps={{content: 'Close'}} Icon={Close} />
```

### Sizes

The component supports four sizes.

```tsx
<Inline space={12} alignY="center">
    <IconButton tooltipProps={{content: 'Close'}} variant={'primary'} Icon={Close} size={'extraSmall'} />
    <IconButton tooltipProps={{content: 'Close'}} variant={'primary'} Icon={Close} size={'small'} />
    <IconButton
        tooltipProps={{content: 'Close'}}
        variant={'primary'}
        Icon={Close}
        size={'medium'}
    />
    <IconButton tooltipProps={{content: 'Close'}} variant={'primary'} Icon={Close} size={'large'} />
```

### Icon

Use the `Icon` prop to specify which of our [icons](/graphic-elements/icons/icons.overview) to show in the button.

```tsx
<IconButton tooltipProps={{content: 'More options'}} variant={'secondary'} Icon={Options} />
```

### Tooltip

The component comes with a required [Tooltip](/components/web/tooltip/tooltip.guidelines) to ensure clarity around the button's function. See the [Tooltip component's API](/components/web/tooltip/tooltip.code#api-reference) for details.

```tsx
<IconButton tooltipProps={{content: 'Close', side: 'right'}} variant={'secondary'} Icon={Close} />
```

#### Omiting the Tooltip

If the icon within a button is widely recognised and clearly conveys the associated action (e.g., a "close" icon in a Modal component), it is acceptable to omit the tooltip.

> See [the Accessibility section](#accessibility) for details

```tsx
<IconButton tooltipProps={{'aria-label': 'Close', dangerouslyOmitTooltip: true}} Icon={Close} />
```

Please refer to the [WCAG guidelines](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA14#examples) for more information on when this is sufficient.

### Disabled

Pass the `disabled` prop to disable all interactions with the button.

```tsx
<IconButton disabled tooltipProps={{content: 'Close'}} variant={'secondary'} Icon={Close} />
```

### Skeleton

Use a "skeleton" version of this component to display a loading state while data is being fetched. It provides a visual placeholder, giving users a preview of the UI structure before the actual content is loaded. This enhances the user experience by offering a more accurate representation of the final layout during data retrieval.

```tsx
<IconButton skeleton tooltipProps={{content: 'Close'}} variant={'secondary'} Icon={Close} />
```

## Accessibility

By default, the `aria-label` is automatically generated from the `content` prop in `tooltipProps`, but only when the `content` is a `string`. If the generated label isn't descriptive enough, if the content is not suitable for screen readers, or if `dangerouslyOmitTooltip` is enabled, you should manually provide an `aria-label` for accessibility.

When the button is `hovered` or `focused`, the `aria-label` is removed, and an `aria-describedby` attribute is added, pointing to the element containing the tooltip's content. This ensures assistive technologies announce only the `aria-describedby` content, avoiding duplicate announcements.

## Related components

- [Button](/components/web/button/button.guidelines): A clickable element which communicates that users can trigger an action.
- [Button group](/components/web/button-group/button-group.guidelines): A layout component used to group multiple related actions a user can take.