# Pill

Page: /docs/components/pill

{/* Figma: Meridian → Pill (docs 37:14, component set 17:201). Spec: docs/design-system/meridian/pill.md */}

A property you can set, in a round 28 pill: a topic, a region, a format or a date. Clicking it opens its menu. On the site Pills filter the guides library, events and the integrations directory. Pills are properties, not values (Tag), statuses (Badge) or actions (Button).

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { Pill } from "@commenda/meridian/ui/pill";
import { USFlag } from "@commenda/pathfinder/flags";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import { Tag01Icon } from "@commenda/pathfinder/icons/Tag01Icon";
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 PillEmptySet() {
	return (
		<Stage>
			<Labelled label="empty">
				<Pill label="Topic" leading={<Tag01Icon />} />
			</Labelled>
			<Labelled label="set">
				<Pill label="Topic" value="Sales tax" leading={<Tag01Icon />} />
			</Labelled>
			<Labelled label="more than one: +N">
				<Pill
					label="Region"
					value="United States"
					additionalCount={2}
					leading={<USFlag size={16} />}
				/>
			</Labelled>
			<Labelled label="row more: IconButton">
				<IconButton size="sm" label="More filters">
					<DotsHorizontalIcon />
				</IconButton>
			</Labelled>
		</Stage>
	);
}
```

## Usage [#usage]

```tsx
import { Pill } from "@commenda/meridian/ui/pill";

<Pill label="Topic" value={topic} leading={<Tag01Icon />} onClick={openTopicMenu} />;
```

## Empty or set [#empty-or-set]

Empty shows the property name in Soft Pearl 900. Set shows the value in 1000. More than one value adds +N. The row’s more menu is an IconButton.

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { Pill } from "@commenda/meridian/ui/pill";
import { USFlag } from "@commenda/pathfinder/flags";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import { Tag01Icon } from "@commenda/pathfinder/icons/Tag01Icon";
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 PillEmptySet() {
	return (
		<Stage>
			<Labelled label="empty">
				<Pill label="Topic" leading={<Tag01Icon />} />
			</Labelled>
			<Labelled label="set">
				<Pill label="Topic" value="Sales tax" leading={<Tag01Icon />} />
			</Labelled>
			<Labelled label="more than one: +N">
				<Pill
					label="Region"
					value="United States"
					additionalCount={2}
					leading={<USFlag size={16} />}
				/>
			</Labelled>
			<Labelled label="row more: IconButton">
				<IconButton size="sm" label="More filters">
					<DotsHorizontalIcon />
				</IconButton>
			</Labelled>
		</Stage>
	);
}
```

## Leading [#leading]

One 16 slot for whatever identifies the value: an icon, a status, a person’s avatar or a country’s flag.

```tsx
import { Pill } from "@commenda/meridian/ui/pill";
import { GBFlag } from "@commenda/pathfinder/flags";
import { CalendarIcon } from "@commenda/pathfinder/icons/CalendarIcon";
import { CheckCircleIcon } from "@commenda/pathfinder/icons/CheckCircleIcon";
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 PillLeading() {
	return (
		<Stage>
			<Labelled label="icon">
				<Pill label="Date" value="Nov 18" leading={<CalendarIcon />} />
			</Labelled>
			<Labelled label="status">
				<Pill label="Status" value="Live now" leading={<CheckCircleIcon />} />
			</Labelled>
			<Labelled label="flag">
				<Pill label="Region" value="United Kingdom" leading={<GBFlag size={16} />} />
			</Labelled>
		</Stage>
	);
}
```

## States [#states]

Hover and open fill Soft Pearl 200, color only. Open holds the hover fill while its menu shows. Focus adds the blue ring, outside the pill. Read-only drops the fill and the hairline.

```tsx
import { Pill } from "@commenda/meridian/ui/pill";
import { CalendarIcon } from "@commenda/pathfinder/icons/CalendarIcon";
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 PillStates() {
	return (
		<Stage>
			<Labelled label="default">
				<Pill label="Date" value="Nov 18" leading={<CalendarIcon />} />
			</Labelled>
			<Labelled label="disabled">
				<Pill label="Date" value="Nov 18" leading={<CalendarIcon />} disabled />
			</Labelled>
			<Labelled label="read-only">
				<Pill label="Date" value="Nov 18" leading={<CalendarIcon />} readOnly />
			</Labelled>
		</Stage>
	);
}
```

## In a filter row [#in-a-filter-row]

A row of filters above the guides library: topic, region and format, with the more menu for the rest.

```tsx
import { IconButton } from "@commenda/meridian/ui/icon-button";
import { Pill } from "@commenda/meridian/ui/pill";
import { USFlag } from "@commenda/pathfinder/flags";
import { DotsHorizontalIcon } from "@commenda/pathfinder/icons/DotsHorizontalIcon";
import { File02Icon } from "@commenda/pathfinder/icons/File02Icon";
import { Tag01Icon } from "@commenda/pathfinder/icons/Tag01Icon";

export function PillFilterRow() {
	return (
		<div className="not-prose my-4 rounded-xl border border-fd-border bg-white p-8">
			<p className="mb-4 font-medium text-lg">Guides and playbooks</p>
			<div className="flex flex-wrap items-center gap-1.5">
				<Pill label="Topic" value="Sales tax" leading={<Tag01Icon />} />
				<Pill label="Region" value="United States" leading={<USFlag size={16} />} />
				<Pill label="Format" leading={<File02Icon />} />
				<IconButton size="sm" label="More filters">
					<DotsHorizontalIcon />
				</IconButton>
			</div>
		</div>
	);
}
```

## Anatomy [#anatomy]

Background with a 0.5 Soft Pearl 300 hairline, fully round, 8 on the left and 12 on the right, 6 between parts. Label/12 Strong in Soft Pearl 1000, the count in 800. The leading slot is 16. Height 28.

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` | Property name, retained in the accessible name when a value is shown. |
| `value` | `string` |  |
| `leading` | `ReactNode` |  |
| `additionalCount` | `number` | Number of additional values beyond the displayed value. |
| `readOnly` | `boolean` |  |

## Best practices [#best-practices]

- Use a Pill for a property people can set: a topic, region, format or date on a filter row. Clicking it opens that property’s menu.
- A value chosen inside a field is a Tag, a status is a Badge, and an action is a Button. A Pill never removes itself and never runs an action.
- An empty Pill names its property ("Topic", "Region") in Soft Pearl 900, so a row shows what is not set. Once set, it shows the value.
- More than one value shows the first and +N; the menu lists them all. Labels truncate past 240 and show in full on hover.
- Lead with what identifies the value: a country’s flag, a person’s avatar, a status icon. Otherwise use the property’s icon.
- A row of Pills sits 6 apart and wraps at its container’s edge. The row’s more menu is IconButton tertiary sm, not a Pill.
- Source: Pathfinder Pill. Meridian keeps it as is.
