# Icon Button

Button designed specifically for usage with a single icon.

```jsx
<IconButton>
  <MagnifyingGlassIcon width="18" height="18" />
</IconButton>
```

## [API Reference](#api-reference)

This component is based on the `button` element and supports [common margin props](/themes/docs/overview/layout#margin-props).

| Prop           | Type                                                 | Default          |
| -------------- | ---------------------------------------------------- | ---------------- |
| `asChild`      | `boolean`                                            | No default value |
| `size`         | `Responsive<"1" \| "2" \| "3" \| "4">`               | `"2"`            |
| `variant`      | `enum`                                               | `"solid"`        |
| `color`        | `enum`                                               | No default value |
| `highContrast` | `boolean`                                            | No default value |
| `radius`       | `"none" \| "small" \| "medium" \| "large" \| "full"` | No default value |
| `loading`      | `boolean`                                            | `false`          |

## [Examples](#examples)

It's strongly recommended to include an<!-- --> [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) <!-- -->or<!-- --> [`aria-labelledby`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) <!-- -->prop on Icon Button components since they don't contain visible text. Screen readers rely on this label to announce the button's purpose to users.

### [Size](#size)

Use the `size` prop to control the size of the button.

```jsx
<Flex align="center" gap="3">
  <IconButton size="1" variant="soft">
    <MagnifyingGlassIcon width="15" height="15" />
  </IconButton>

  <IconButton size="2" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton size="3" variant="soft">
    <MagnifyingGlassIcon width="22" height="22" />
  </IconButton>
</Flex>
```

### [Variant](#variant)

Use the `variant` prop to control the visual style of the button.

```jsx
<Flex gap="3">
  <IconButton variant="classic">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="solid">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="surface">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton variant="outline">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>
```

#### Ghost

Use the `ghost` variant to display a button without chrome. Ghost buttons behave like text in layout, as they use a negative margin to optically align themselves against their siblings while maintaining the padding in active and hover states.

```jsx
<IconButton variant="ghost">
  <MagnifyingGlassIcon width="18" height="18" />
</IconButton>
```

### [Color](#color)

Use the `color` prop to assign a specific [color](/themes/docs/theme/color).

```jsx
<Flex gap="3">
  <IconButton color="crimson" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton color="indigo" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton color="grass" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton color="orange" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>
```

### [High-contrast](#high-contrast)

Use the `highContrast` prop to increase color contrast with the background.

```jsx
<Flex direction="column" gap="3">
  <Flex gap="3">
    <IconButton color="gray" variant="classic">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="solid">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="soft">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="surface">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="outline">
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>
  </Flex>

  <Flex gap="3">
    <IconButton color="gray" variant="classic" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="solid" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="soft" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="surface" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>

    <IconButton color="gray" variant="outline" highContrast>
      <MagnifyingGlassIcon width="18" height="18" />
    </IconButton>
  </Flex>
</Flex>
```

### [Radius](#radius)

Use the `radius` prop to assign a specific radius value.

```jsx
<Flex gap="3">
  <IconButton radius="none" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton radius="large" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton radius="full" variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>
```

### [Loading](#loading)

Use the `loading` prop to display a loading spinner in place of button content. The button will be disabled while loading.

```jsx
<Flex gap="3">
  <IconButton loading variant="classic">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="solid">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="soft">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="surface">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>

  <IconButton loading variant="outline">
    <MagnifyingGlassIcon width="18" height="18" />
  </IconButton>
</Flex>
```

<!--$-->

<!--/$-->