Pill

Anatomy

import {Pill} from '@staffbase/design';

<Pill />;

Examples

Variants

Colors

API reference

When to use

• To show the status of a content item or system, such as Draft, Published, or Processing.
• To tag or categorize content with a short, at-a-glance label.
• When the label is supporting metadata of 1–3 words, not a primary action or heading.

When not to use

• Don’t use a Pill as an interactive control — Pills are not clickable or focusable — use Button with variant="ghost" instead.
• Don’t use a Pill as a trigger for a tooltip or popover — use a focusable Button as the trigger instead.
• Don’t use a Pill for a count or notification indicator — use Badge instead.
• Don’t use a Pill for long text or full sentences — use body text instead.
• Don’t use an icon-only Pill — a Pill is a text label by definition. An icon without text forces you to hide a label in aria-label, which means the visible content isn’t self-explanatory to sighted users either. Always pair an icon with visible text.

How to use

Variants

Variant controls visual weight, not meaning. Pair it with color to convey status.

• solid (default) — filled background; higher emphasis, for primary status.
• outline — bordered; lower emphasis, for dense or secondary contexts.

Color

Color is semantic — choose it by meaning, never for decoration alone.

Icon & label

• Pills support a leading or trailing icon alongside a text label. Never use an icon on its own.
• Only use an icon that is universally understood and strongly associated with the label text.
• Avoid decorative-only icons.
• Skip icons in dense tables or lists with many repeating Pills — they add visual noise and reduce scannability.

Layout & spacing

• When grouping Pills next to each other, always use 8px spacing for consistency.

Accessibility

• Pills are display-only: they are never focusable and never act as an interactive trigger.
• Never rely on color alone to convey status — always pair it with text.
• Never rely on an icon alone — always pair it with visible text.

Content & UX copy

• Keep labels 1–3 words in Title Case.
• In a series, keep labels all nouns or all verbs when possible.
• Use past tense for completed actions, such as Published.
• Use the present -ing form for ongoing actions, such as Processing or Importing.
• As a status message, describe the state a file, content item, or system is in, and reuse terms users already see in the interface.
• Examples: Draft, Published / Unpublished, Scheduled, Processing, Approved, Removed, Sent, Completed.