IconButton
An action shown only as an icon, with a tooltip.
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.
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
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
<IconButton label="More actions">
<DotsHorizontalIcon />
</IconButton>;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.
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
sm to lg match Button heights. xs 24 lives only inside another control: clearing an input, closing a tag.
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
Hover and pressed come from the pointer, focus from the keyboard only. Open holds the hover look while its menu is up.
Hover, press and Tab to see the other states. Every button shows its label as a tooltip.
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
The jobs IconButton does on the site, at the size and variant each one takes.
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
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
| Prop | Type | Description |
|---|---|---|
labelRequired | string | From Pathfinder. |
childrenRequired | ReactElement<unknown, string | JSXElementConstructor<any>> | From Pathfinder. |
className | string | From Pathfinder. |
size | "md" | "lg" | "xs" | "sm" | From Pathfinder. |
disabledReason | string | From Pathfinder. |
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. |
variantConditional | "primary" | "secondary" | "tertiary" | "plain" | From Pathfinder. |
destructive | boolean | false | From Pathfinder. |
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.