# IconButton

Page: /docs/components/icon-button

{/* Figma: Meridian → IconButton (docs 27:170, component set 17:7021). Spec: docs/design-system/meridian/icon-button.md */}

An action shown only as an icon: a square Button with the same variants, colors, focus ring and motion. Heights match Button so rows line up. Its label is required and shows as a tooltip.

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import { Trash01Icon } from "@commenda/pathfinder/icons/Trash01Icon";
import type { ReactNode } from "react";

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function IconButtonVariants() {
	return (
		<div className="not-prose my-4 flex flex-col gap-6 rounded-xl border border-fd-border bg-white p-8">
			<div className="flex flex-wrap items-end gap-6">
				{(["tertiary", "secondary", "primary"] as const).map((variant) => (
					<Labelled key={variant} label={variant}>
						<IconButton variant={variant} label="More actions">
							<DotsHorizontalIcon />
						</IconButton>
					</Labelled>
				))}
			</div>
			<div className="flex flex-wrap items-end gap-6">
				{(["tertiary", "secondary", "primary"] as const).map((variant) => (
					<Labelled key={variant} label={`${variant} · destructive`}>
						<IconButton variant={variant} destructive label="Remove this row">
							<Trash01Icon />
						</IconButton>
					</Labelled>
				))}
			</div>
		</div>
	);
}
```

## Usage [#usage]

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";

<IconButton label="More actions">
  <DotsHorizontalIcon />
</IconButton>;
```

## Variants [#variants]

Tertiary for the quiet, repeated actions most icon buttons are. Secondary when the control needs an edge. Primary only for the one main icon action, like Send.

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import { Trash01Icon } from "@commenda/pathfinder/icons/Trash01Icon";
import type { ReactNode } from "react";

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function IconButtonVariants() {
	return (
		<div className="not-prose my-4 flex flex-col gap-6 rounded-xl border border-fd-border bg-white p-8">
			<div className="flex flex-wrap items-end gap-6">
				{(["tertiary", "secondary", "primary"] as const).map((variant) => (
					<Labelled key={variant} label={variant}>
						<IconButton variant={variant} label="More actions">
							<DotsHorizontalIcon />
						</IconButton>
					</Labelled>
				))}
			</div>
			<div className="flex flex-wrap items-end gap-6">
				{(["tertiary", "secondary", "primary"] as const).map((variant) => (
					<Labelled key={variant} label={`${variant} · destructive`}>
						<IconButton variant={variant} destructive label="Remove this row">
							<Trash01Icon />
						</IconButton>
					</Labelled>
				))}
			</div>
		</div>
	);
}
```

## Sizes [#sizes]

sm to lg match Button heights. xs 24 lives only inside another control: clearing an input, closing a tag.

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function IconButtonSizes() {
	return (
		<Stage>
			{(
				[
					["xs", "xs · 24"],
					["sm", "sm · 28"],
					["md", "md · 32"],
					["lg", "lg · 36"],
				] as const
			).map(([size, label]) => (
				<Labelled key={size} label={label}>
					<IconButton size={size} variant="secondary" label="More actions">
						<DotsHorizontalIcon />
					</IconButton>
				</Labelled>
			))}
		</Stage>
	);
}
```

## States [#states]

Hover and pressed come from the pointer, focus from the keyboard only. Open holds the hover look while its menu is up.

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import type { ReactNode } from "react";

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function IconButtonStates() {
	return (
		<div className="not-prose my-4 flex flex-col gap-6 rounded-xl border border-fd-border bg-white p-8">
			{(["tertiary", "secondary", "primary"] as const).map((variant) => (
				<div key={variant} className="flex flex-wrap items-end gap-6">
					<Labelled label={`${variant} · default`}>
						<IconButton variant={variant} label="More actions">
							<DotsHorizontalIcon />
						</IconButton>
					</Labelled>
					<Labelled label="disabled">
						<IconButton
							variant={variant}
							label="More actions"
							disabled
							disabledReason="Nothing to show yet"
						>
							<DotsHorizontalIcon />
						</IconButton>
					</Labelled>
				</div>
			))}
			<p className="text-[12px] text-fd-muted-foreground">
				Hover, press and Tab to see the other states. Every button shows its label as a tooltip.
			</p>
		</div>
	);
}
```

## Common uses [#common-uses]

The jobs IconButton does on the site, at the size and variant each one takes.

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { ChevronLeftIcon } from "@commenda/pathfinder/icons/ChevronLeftIcon";
import { ChevronRightIcon } from "@commenda/pathfinder/icons/ChevronRightIcon";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import { LayoutLeftIcon } from "@commenda/pathfinder/icons/LayoutLeftIcon";
import { Send01Icon } from "@commenda/pathfinder/icons/Send01Icon";
import { Trash01Icon } from "@commenda/pathfinder/icons/Trash01Icon";
import { XCloseIcon } from "@commenda/pathfinder/icons/XCloseIcon";
import type { ReactNode } from "react";

function Stage({ children }: { children: ReactNode }) {
	return (
		<div className="not-prose my-4 flex flex-wrap items-end gap-6 rounded-xl border border-fd-border bg-white p-8">
			{children}
		</div>
	);
}

function Labelled({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex flex-col items-center gap-2.5">
			{children}
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
		</div>
	);
}

export function IconButtonCommonUses() {
	return (
		<Stage>
			<Labelled label="More">
				<IconButton size="sm" label="More actions">
					<DotsHorizontalIcon />
				</IconButton>
			</Labelled>
			<Labelled label="Remove a row">
				<IconButton size="sm" destructive label="Remove this row">
					<Trash01Icon />
				</IconButton>
			</Labelled>
			<Labelled label="Close, clear">
				<IconButton size="xs" label="Close the demo form">
					<XCloseIcon />
				</IconButton>
			</Labelled>
			<Labelled label="Previous">
				<IconButton size="sm" variant="secondary" label="Previous customer story">
					<ChevronLeftIcon />
				</IconButton>
			</Labelled>
			<Labelled label="Next">
				<IconButton size="sm" variant="secondary" label="Next customer story">
					<ChevronRightIcon />
				</IconButton>
			</Labelled>
			<Labelled label="Toggle a panel">
				<IconButton size="md" variant="secondary" label="Show the side panel">
					<LayoutLeftIcon />
				</IconButton>
			</Labelled>
			<Labelled label="Send">
				<IconButton size="lg" variant="primary" label="Send message">
					<Send01Icon />
				</IconButton>
			</Labelled>
		</Stage>
	);
}
```

## Anatomy [#anatomy]

A square container and one centered icon. The icon is 16 at xs to md and 20 at lg, and takes the variant color.

| Part | Value |
| --- | --- |
| Container | xs 24 · sm 28 · md 32 (`control/md`) · lg 36 |
| Radius | 8 (`radius/md`) |
| Icon | 16 at xs–md, 20 at lg |

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `children` (required) | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |
| `className` | `string` |  |
| `size` | `"md" \| "lg" \| "xs" \| "sm"` |  |
| `disabledReason` | `string` |  |
| `tooltip` | `boolean` | Disable the automatic hint when an explicit Tooltip wraps this control. |
| `style` | `CSSProperties \| ((state: ButtonState) => CSSProperties \| undefined)` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `focusableWhenDisabled` | `boolean` | Whether the button should be focusable when disabled. |
| `nativeButton` | `boolean` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ButtonState>` | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| `variant` (conditional) | `"primary" \| "secondary" \| "tertiary" \| "plain"` |  |
| `destructive` | `boolean \| false` |  |

## Best practices [#best-practices]

- Use it for actions people know by their icon: the more menu, close, remove, previous and next on a carousel, panel toggles. Primary is only for the one main icon action, like Send.
- If people would not recognize the icon without words, use a Button with a left icon instead.
- The label is required. It names the action and its target ("Close the demo form"), not the icon ("X"), and the tooltip repeats it.
- Match heights in a row: an md IconButton beside md Buttons, an lg beside lg.
- xs 24 only inside another control. On phones use md or lg; 24 and 28 are below the touch target.
- Source: Pathfinder IconButton. Meridian keeps it as is.
