> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# IconButton

> A button containing only an icon.

```tsx theme={null}
import { IconButton } from "@fanvue/ui";
import type { IconButtonProps, IconButtonSize, IconButtonVariant } from "@fanvue/ui";
```

## Examples

## Primary 40

<Frame>
  <iframe src={"https://main--697a1b6dd4dad73ee9c0e5f5.chromatic.com/iframe.html?id=components-iconbutton--primary-40&viewMode=story&shortcuts=false&singleStory=true&globals=theme:light"} width="100%" height="200" style={{border: "none", borderRadius: "8px"}} loading="lazy" title="IconButton — Primary 40" />
</Frame>

```tsx theme={null}
import { HomeIcon, IconButton } from "@fanvue/ui";

<IconButton variant="primary" size="40" icon={<HomeIcon />} aria-label="Home" />
```

## Fieldset Disabled

V2 variants pick up the disabled treatment via a CSS `disabled:` fallback, so buttons inside a `<fieldset disabled>` are dimmed even without the `disabled` prop.

<Frame>
  <iframe src={"https://main--697a1b6dd4dad73ee9c0e5f5.chromatic.com/iframe.html?id=components-iconbutton--fieldset-disabled&viewMode=story&shortcuts=false&singleStory=true&globals=theme:light"} width="100%" height="200" style={{border: "none", borderRadius: "8px"}} loading="lazy" title="IconButton — Fieldset Disabled" />
</Frame>

```tsx theme={null}
import { HomeIcon, IconButton } from "@fanvue/ui";

<fieldset disabled className="flex items-center gap-4 border-0 p-6">
  {(["primary", "secondary", "tertiary", "outline", "error"] as const).map((variant) => (
    <IconButton
      key={variant}
      variant={variant}
      size="40"
      icon={<HomeIcon />}
      aria-label={`${variant} in disabled fieldset`}
    />
  ))}
</fieldset>
```

## V2 Matrix

<Frame>
  <iframe src={"https://main--697a1b6dd4dad73ee9c0e5f5.chromatic.com/iframe.html?id=components-iconbutton--v-2-matrix&viewMode=story&shortcuts=false&singleStory=true&globals=theme:light"} width="100%" height="200" style={{border: "none", borderRadius: "8px"}} loading="lazy" title="IconButton — V2 Matrix" />
</Frame>

```tsx theme={null}
import { HomeIcon, IconButton } from "@fanvue/ui";

const v2Variants = [
  "primary",
  "secondary",
  "tertiary",
  "outline",
  "error",
  "white",
  "black",
] as const;

const v2Sizes = ["24", "32", "40", "48"] as const;

<div className="flex flex-col gap-6 p-6">
  {v2Variants.map((variant) => (
    <div key={variant} className="flex items-center gap-4">
      <span className="w-20 font-mono text-content-secondary text-xs">{variant}</span>
      {v2Sizes.map((size) => (
        <IconButton
          key={size}
          variant={variant}
          size={size}
          icon={<HomeIcon />}
          aria-label={`${variant} ${size}`}
        />
      ))}
      <IconButton
        variant={variant}
        size="40"
        icon={<HomeIcon />}
        aria-label={`${variant} disabled`}
        disabled
      />
    </div>
  ))}
</div>
```

## Contrast 24

<Frame>
  <iframe src={"https://main--697a1b6dd4dad73ee9c0e5f5.chromatic.com/iframe.html?id=components-iconbutton--contrast-24&viewMode=story&shortcuts=false&singleStory=true&globals=theme:light"} width="100%" height="200" style={{border: "none", borderRadius: "8px"}} loading="lazy" title="IconButton — Contrast 24" />
</Frame>

```tsx theme={null}
import { HomeIcon, IconButton } from "@fanvue/ui";

<IconButton variant="contrast" size="24" icon={<HomeIcon />} />
```

## V2 Negative

<Frame>
  <iframe src={"https://main--697a1b6dd4dad73ee9c0e5f5.chromatic.com/iframe.html?id=components-iconbutton--v-2-negative&viewMode=story&shortcuts=false&singleStory=true&globals=theme:light"} width="100%" height="200" style={{border: "none", borderRadius: "8px"}} loading="lazy" title="IconButton — V2 Negative" />
</Frame>

```tsx theme={null}
import { HomeIcon, IconButton } from "@fanvue/ui";

<div className="flex items-center gap-4 bg-neutral-900 p-6">
  {(["primary", "secondary", "tertiary", "outline"] as const).map((variant) => (
    <IconButton
      key={variant}
      variant={variant}
      size="40"
      negative
      icon={<HomeIcon />}
      aria-label={`${variant} negative`}
    />
  ))}
</div>
```

## Props

## IconButton

A button containing only an icon. Use when an action can be represented by an icon alone (e.g. close, send). Always pair with an `aria-label` for accessibility.

Shape is size-driven for the standard variants: the `24` size is squared (`rounded-xs`), every larger size is circular. Bespoke variants (`brand`, `contrast`, `messaging`, `navTray`, `tertiaryDestructive`, `stop`, `microphone`) stay circular at all sizes. `field` is the exception that is never circular — it takes the inputs' `rounded-sm` so it matches the fields it sits beside. Use it at `32`, `40` or `48`: those are the sizes `Select` offers, and the variant only earns its surface when it lines up with one.

<ParamField path="icon" type="ReactNode" required>
  Icon element to render inside the button.
</ParamField>

<ParamField path="counterValue" type="number">
  When provided, displays a `Count` badge at the top-right corner.
</ParamField>

<ParamField path="negative" type="boolean" default="false">
  Forces the dark-surface treatment regardless of theme. Only honoured on the `primary`, `secondary`, `tertiary`, and `outline` variants.
</ParamField>

<ParamField path="size" type="&#x22;24&#x22; | &#x22;32&#x22; | &#x22;40&#x22; | &#x22;48&#x22; | &#x22;52&#x22; | &#x22;72&#x22;" default="40">
  Size of the button in pixels.
</ParamField>

<ParamField path="variant" type="&#x22;stop&#x22; | &#x22;error&#x22; | &#x22;brand&#x22; | &#x22;primary&#x22; | &#x22;secondary&#x22; | &#x22;tertiary&#x22; | &#x22;outline&#x22; | &#x22;white&#x22; | ..." default="primary">
  Visual style variant of the icon button.

  Full type: `"stop" | "error" | "brand" | "primary" | "secondary" | "tertiary" | "outline" | "white" | "tertiaryDestructive" | "contrast" | "black" | "messaging" | "navTray" | "microphone" | "field"`.
</ParamField>

## Exported types

Also exported from `@fanvue/ui`: `IconButtonProps`, `IconButtonSize`, `IconButtonVariant`.

***

**Setup:** [Installation](/docs/ui/installation) · [Theming](/docs/ui/theming)