# Pill

Source: https://payloadcms.com/docs/beta/ui-components/pill

The `Pill` component displays compact metadata, a category, or a status. Keep its label short so it remains easy to scan.

## Import

Inside a Payload Admin Panel Custom Component:

```tsx
import { Pill } from '@payloadcms/ui'
```

You can also import the component directly:

```tsx
import { Pill } from '@payloadcms/ui/elements/Pill'
```

## Styles

**Implementation**

```tsx
<Pill>Default</Pill>
<Pill pillStyle="dark">Dark</Pill>
<Pill pillStyle="success">Success</Pill>
<Pill pillStyle="warning">Warning</Pill>
<Pill pillStyle="error">Error</Pill>
```

**Styling**

Target a semantic Pill style to customize its background and text without changing the corresponding palette throughout the Admin Panel.

```css
@layer payload {
  .pill--style-success {
    --color-bg-selected: #dff7e8;
    --color-text-brand: #176b3a;
  }

  .pill--style-warning {
    --color-bg-warning-tertiary: #fff0cc;
    --color-text-warning: #714b00;
  }

  .pill--style-error {
    --color-bg-danger-tertiary: #fde5e3;
    --color-text-danger: #9b2924;
  }
}
```

- `--color-bg-selected`: Success Pill background.
- `--color-text-brand`: Success Pill text.
- `--color-bg-warning-tertiary`: Warning Pill background.
- `--color-text-warning`: Warning Pill text.
- `--color-bg-danger-tertiary`: Error Pill background.
- `--color-text-danger`: Error Pill text.

Use semantic styles only when the label represents that state. For example, use `error` for a failed state rather than decoration.

## Shape

**Implementation**

```tsx
<Pill>Default</Pill>
<Pill rounded>Rounded</Pill>
```

**Styling**

Override the default and rounded radius tokens within Pill selectors to change their shapes without altering other controls.

```css
@layer payload {
  .pill {
    --button-radius: 0.25rem;
  }

  .pill--rounded {
    --radius-large: 999px;
  }
}
```

- `--button-radius`: Default Pill corner radius.
- `--radius-large`: Corner radius used when rounded is enabled.

Pills use Payload's standard small corner radius by default. Add `rounded` when the label should use the larger rounded corner treatment.

## Sizes

**Implementation**

```tsx
<Pill size="small">Small</Pill>
<Pill size="medium">Medium</Pill>
```

**Styling**

Adjust spacing tokens within each size class to customize Pill height and inline padding independently.

```css
@layer payload {
  .pill--size-small {
    --spacer-1: 0.375rem;
  }

  .pill--size-medium {
    --spacer-1: 0.375rem;
    --spacer-2-5: 0.875rem;
  }
}
```

- `--spacer-1`: Small spacing used for vertical and compact inline padding.
- `--spacer-2-5`: Medium Pill inline padding.

## Accessibility

- Keep labels concise and ensure their meaning does not depend on color alone.
- Treat a Pill as presentational metadata. Use a Button or Link when the user needs to perform an action.
- Provide an accessible label when an icon communicates information that is not present in the visible text.

## Common props

These are the props most commonly used with this component. See its exported types in `@payloadcms/ui` for the complete list.

| Prop        | Type                                                                                                  | Default    | Description                          |
| ----------- | ----------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------ |
| `children`  | `ReactNode`                                                                                           | —          | Visible pill content.                |
| `pillStyle` | `'light' \| 'light-gray' \| 'dark' \| 'white' \| 'always-white' \| 'success' \| 'warning' \| 'error'` | `'light'`  | Sets the visual style.               |
| `size`      | `'small' \| 'medium'`                                                                                 | `'medium'` | Sets the pill height and spacing.    |
| `rounded`   | `boolean`                                                                                             | `false`    | Uses a larger rounded corner radius. |
| `icon`      | `ReactNode`                                                                                           | —          | Displays an icon beside the label.   |