Skip to content

Design

Pill Buttons are secondary interactive elements used for filtering, tagging, or toggling options within the interface. They are visually lighter than standard buttons and should never be used for primary actions. Two main use cases sit under the same shell: selectable pills that represent filters or toggles, and informational pills that highlight contextual labels or statuses.

Anatomy

Section titled “Anatomy”
  1. Pill button
  2. Icon
  3. Label

When to use it

Section titled “When to use it”

Use a Pill Button when:

  • You need lightweight, secondary interactions like filters or tag selectors.
  • You want to group related options horizontally (e.g. category filters).
  • A clear selected / unselected visual state is part of the pattern.

Avoid the Pill Button when:

  • The action represents a primary call to action — use Primary Button instead.
  • The action leads to navigation — use a Link Button.
  • You need destructive or confirmatory actions — use Secondary or Alert Buttons.

Properties

Section titled “Properties”

Type

Four colour treatments — Neutral, Contrast, OnOverlay Light, and OnOverlay C2A — each tuned to a different surface. Use Neutral on standard light backgrounds, Contrast on dark, and the OnOverlay variants when the pill sits over imagery or video.

State

Rested, Hover, Active (selected), Disabled, and Focus. Active carries the selected visual; disabled keeps the shape but mutes the colour; focus shows a 2 px outline so the control stays reachable from the keyboard.

Size

Three text sizes — Large for prominent filter areas, Medium as the default, Small for dense layouts. The pill always hugs its label and keeps the rounded shape regardless of size.

Icon

Optional leading and trailing icons. Pair them with the label only when they add meaning (a chevron for a dropdown trigger, a spinner during loading); icon-only pills aren’t supported.

Platform considerations

Section titled “Platform considerations”

Desktop

Pointer accuracy is high, but keep at least 8 px between adjacent pills so the hit areas don’t crowd each other in dense filter rows.

Tablet

Mix of touch and pointer — the medium size handles both. Keep the 44 px touch area honoured even when the visual height drops below it (use invisible padding).

Mobile

Touch-first. Stick to medium or large pills wherever possible and pay close attention to spacing so users don’t tap the wrong filter.

Best practices

Section titled “Best practices”

Keep pills lightweight and visually distinct from primary actions.

Do

Add invisible padding around pills when needed to expand the touch target without altering the visual, keep at least 8 px horizontally and 4 px vertically between adjacent pills, and make sure each pill carries visible text and a clearly distinguishable focus state.

Don't

Don’t rely on the visible shape alone to define the touch area, don’t define touch areas smaller than 24×24 px even for compact pills, and don’t place pills close enough that their touch areas overlap.

Content guidelines

Section titled “Content guidelines”

Pill labels must clearly describe what they do or what they represent. Keep filter labels to 1–2 words (“Electric”, “In stock”) and action labels to 1–3 (“Apply”, “Show all”). Use clear, specific text that stands on its own — users shouldn’t need to read nearby copy to understand a pill — and avoid vague labels like “OK”, “Click”, or “Select”. Stay under 24–30 characters to keep translations and responsive layouts well-behaved, use sentence case (“Apply filter”, not “APPLY FILTER”), and skip trailing punctuation. Use neutral, easily localisable phrasing — avoid idioms or culture-specific references. Never truncate; wrap to a new line if the label needs more room.