# Button

Page: /docs/components/button

{/* Figma: Meridian → Button (docs 14:53, component set 12:633). Spec: docs/design-system/meridian/button.md */}

Starts an action. Pathfinder Button with one more size, xl 40, so a button sits next to the 40 Input, and a link-arrow variant for card and section links. Five variants, three sizes and seven states.

Click **Save changes** to preview loading and completion. It resets on its own so you can try again.

```tsx
"use client";

import { Button } from "@commenda/meridian/ui/button";
import { useState } from "react";
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>
	);
}

/** Click to run loading → done, then it resets, like Pathfinder's feedback demo. */
export function ButtonFeedback() {
	const [phase, setPhase] = useState<"idle" | "loading" | "done">("idle");
	const run = () => {
		setPhase("loading");
		setTimeout(() => setPhase("done"), 1200);
		setTimeout(() => setPhase("idle"), 2700);
	};
	return (
		<Stage>
			<Button
				size="xl"
				onClick={phase === "idle" ? run : undefined}
				loadingConfig={{ isLoading: phase === "loading", label: "Saving" }}
				completionConfig={{ isComplete: phase === "done", label: "Saved" }}
			>
				Save changes
			</Button>
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { Button } from "@commenda/meridian/ui/button";

<Button size="xl" onClick={onSave}>Save changes</Button>;

// Navigation is a real link: render the button as an anchor.
<Button size="xl" nativeButton={false} render={<a href="/book-a-demo" />}>
  Book a demo
</Button>;
```

The Pathfinder stylesheet comes with the component; there is nothing else to import.

## Sizes [#sizes]

md 32 inside cards and tables, lg 36 in the nav and on phones, xl 40 for page CTAs. Height comes from the control token; width hugs the label.

```tsx
import { Button } from "@commenda/meridian/ui/button";
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 ButtonSizes() {
	return (
		<Stage>
			<Labelled label="md · 32">
				<Button size="md">Book a demo</Button>
			</Labelled>
			<Labelled label="lg · 36">
				<Button size="lg">Book a demo</Button>
			</Labelled>
			<Labelled label="xl · 40">
				<Button size="xl">Book a demo</Button>
			</Labelled>
		</Stage>
	);
}
```

## Variants [#variants]

Primary for the one main action in a view, secondary beside it, tertiary for quiet repeated actions. Link sits inline with copy; link-arrow ends a card or section.

```tsx
import { Button } from "@commenda/meridian/ui/button";
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 ButtonVariants() {
	return (
		<Stage>
			<Labelled label="primary">
				<Button size="xl">Book a demo</Button>
			</Labelled>
			<Labelled label="secondary">
				<Button size="xl" variant="secondary">
					Talk to sales
				</Button>
			</Labelled>
			<Labelled label="tertiary">
				<Button size="xl" variant="tertiary">
					See pricing
				</Button>
			</Labelled>
			<Labelled label="link">
				<Button size="xl" variant="link">
					Learn more
				</Button>
			</Labelled>
			<Labelled label="link-arrow">
				<Button size="xl" variant="link-arrow">
					Read the story
				</Button>
			</Labelled>
		</Stage>
	);
}
```

## Icons [#icons]

A left icon only when it adds meaning. A right icon for a trailing arrow. link-arrow always carries its arrow.

```tsx
import { Button } from "@commenda/meridian/ui/button";
import { ArrowRightIcon } from "@commenda/pathfinder/icons/ArrowRightIcon";
import { PlusIcon } from "@commenda/pathfinder/icons/PlusIcon";
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>
	);
}

export function ButtonIcons() {
	return (
		<Stage>
			<Button size="xl" variant="secondary" leadingIcon={<PlusIcon />}>
				Download the guide
			</Button>
			<Button size="xl" trailingIcon={<ArrowRightIcon />}>
				Get started
			</Button>
			<Button size="xl" variant="link-arrow">
				See all integrations
			</Button>
		</Stage>
	);
}
```

## States [#states]

Hover and pressed come from interaction, focus only from the keyboard. Loading puts the spinner beside the label; done confirms with a check. Disabled stays focusable and can explain why.

```tsx
import { Button } from "@commenda/meridian/ui/button";
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>
	);
}

/** Static states: hover and pressed come from the pointer, focus from Tab. */
export function ButtonStates() {
	const rows = [
		["primary", "Book a demo"],
		["secondary", "Book a demo"],
		["tertiary", "Book a demo"],
	] as const;
	return (
		<div className="not-prose my-4 flex flex-col gap-6 rounded-xl border border-fd-border bg-white p-8">
			{rows.map(([variant, label]) => (
				<div key={variant} className="flex flex-wrap items-end gap-6">
					<Labelled label="default">
						<Button size="lg" variant={variant}>
							{label}
						</Button>
					</Labelled>
					<Labelled label="disabled">
						<Button size="lg" variant={variant} disabled>
							{label}
						</Button>
					</Labelled>
					<Labelled label="loading">
						<Button
							size="lg"
							variant={variant}
							loadingConfig={{ isLoading: true, label: "Saving" }}
						>
							{label}
						</Button>
					</Labelled>
					<Labelled label="done">
						<Button
							size="lg"
							variant={variant}
							completionConfig={{ isComplete: true, label: "Saved" }}
						>
							{label}
						</Button>
					</Labelled>
				</div>
			))}
			<div className="flex flex-wrap items-end gap-6">
				<Labelled label="default">
					<Button size="lg" variant="link-arrow">
						Book a demo
					</Button>
				</Labelled>
				<Labelled label="disabled">
					<Button size="lg" variant="link-arrow" disabled>
						Book a demo
					</Button>
				</Labelled>
			</div>
			<p className="text-[12px] text-fd-muted-foreground">
				Hover and press any button above; Tab to see focus.
			</p>
		</div>
	);
}
```

## Next to an input [#next-to-an-input]

A button beside a field is always xl 40, 12 apart. On phones they stack, both full width.

```tsx
import { Button } from "@commenda/meridian/ui/button";
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>
	);
}

export function ButtonNextToInput() {
	return (
		<Stage>
			<div className="flex w-full max-w-md flex-col gap-3 sm:flex-row">
				{/* Placeholder field until Meridian Input lands: 40 tall, border/default. */}
				<input
					type="email"
					placeholder="Enter your work email"
					className="h-10 min-w-0 flex-1 rounded-lg border border-(--pf-color-soft-pearl-400) bg-white px-4 text-base"
				/>
				<Button size="xl">Book a demo</Button>
			</div>
		</Stage>
	);
}
```

## Anatomy [#anatomy]

Every part is optional except the container and label. Icons take the label colour.

| Part | md · lg | xl |
| --- | --- | --- |
| Container height | 32 · 36 (`control/md`, `control/lg`) | 40 (`control/xl`) |
| Padding | 12 | 16 (`spacing/xl`) |
| Gap, label to icon | 6 | 8 (`spacing/md`) |
| Icon | 16 · 20 | 20 |
| Label | Label/13 Strong · Label/15 Strong | Label/16 Strong |
| Radius | 8 (`radius/md`) | 8 (`radius/md`) |

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `variant` | `"link" \| "primary" \| "secondary" \| "tertiary" \| "link-arrow"` | Figma `variant`. One primary per view. |
| `size` | `"md" \| "lg" \| "xl"` | Figma `size`: md 32 in cards and tables, lg 36 in the nav and on phones, xl 40 for page CTAs. |
| `completionConfig` | `CompletionConfig` | Figma state `done`: the label and check shown after a successful action. |
| `className` | `string` |  |
| `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. |
| `loadingConfig` | `LoadingConfig` |  |
| `leadingIcon` | `ReactNode` |  |
| `trailingIcon` | `ReactNode` |  |
| `disabledReason` | `string` |  |

**`completionConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isComplete` (required) | `boolean` |  |
| `label` (required) | `string` |  |
| `icon` | `ReactNode` |  |

**`loadingConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isLoading` (required) | `boolean` |  |
| `label` | `string` |  |

## Best practices [#best-practices]

- One primary per view. Everything beside it is secondary or tertiary.
- 12 between buttons. Labels never wrap: shorten the label instead.
- A button next to an Input is xl 40, the same height as the field.
- On phones every button is lg 36, or full-width xl under an input.
- "Book a demo" goes to /book-a-demo.
- Source: Pathfinder Button. Meridian adds size xl and variant link-arrow; everything else matches Pathfinder.
