@workday/canvas-kit-docs/dist/mdx/preview-react/pill/Pill.mdx

Documentation components of Canvas Kit components

import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';

import WithReadOnly from './examples/WithReadOnly';
import WithAvatar from './examples/WithAvatar';
import Basic from './examples/Basic';
import WithCount from './examples/WithCount';
import WithRemovable from './examples/WithRemovable';
import WithList from './examples/WithList';
import CustomStyles from './examples/CustomStyles';


# Canvas Kit Pill

`Pill`s are static or interactive indicators that allow users to input, filter, or label
information.

## Installation

```sh
yarn add @workday/canvas-kit-preview-react
```

## Usage

`Pill`s are used to visually label objects on a page for quick recognition. They’re offered as both
static (read-only) and interactive elements. They allow users to filter a list or table, or label
information to help with scanning and organization.

### Basic Pills

By default a Pill is considered interactive. All leading elements (icons or avatars) are intended to
be descriptive, helping support the label. Do not rely on the leading element to indicate the
interaction behavior.

#### Icon

You can render an icon inside the `Pill` with `Pill.Icon`. It will render a `plusIcon` by default,
but it can be customized by providing an icon to the `icon` prop. Because it uses `SystemIcon` under
the hood, you also have access to all `SystemIconProps`.

#### Accessibility

You must provide an `aria-label` to the `Pill.Icon` for proper accessibility.

<ExampleCodeBlock code={Basic} />

#### Avatar

You can render an avatar image inside the `Pill` with `Pill.Avatar`. It should appear before the
`Pill` text. Because it uses `Avatar` under the hood, you also have access to all `AvatarProps`.

<ExampleCodeBlock code={WithAvatar} />

#### Count

The count appears after the label. It is usually associated with the label. If you have a category,
the count will directly correlate to that category.

<ExampleCodeBlock code={WithCount} />

### Read Only

The `readOnly` variant is a non-interactive element that is used to display information.

You can define a read only `Pill` by providing a `variant='readOnly'` prop.

<ExampleCodeBlock code={WithReadOnly} />

### Removable Pills

Removable `Pill`s display an `X` icon after the label. They have a smaller, more specific focus
state and click target to be more intentional about their actions and to avoid unintended removal.

You can define a removable `Pill` by providing a `variant='removable'` prop.

```tsx
<Pill variant="removable">
  Pink Shirts
  <Pill.IconButton onClick={() => console.warn('clicked')} />
</Pill>
```

In this case, we use a `Pill.IconButton` because the `X` becomes the focusable and clickable
element.

The default icon for `Pill.IconButton` is `xSmallIcon` but this can also be overwritten by passing
an `icon` prop to `Pill.IconButton`

<ExampleCodeBlock code={WithRemovable} />

### List of Pills

`Pill`s can often represent multiple pieces of information such as a filtered list of categories or
skills.

In order to achieve this, use our `Flex` component to wrap each `Pill` and space them out
accordingly.

<ExampleCodeBlock code={WithList} />

### Custom Styles

`Pill` supports custom styling via the `cs` prop. For more information, check our
["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs)
or view the example below.

<ExampleCodeBlock code={CustomStyles} />

## Component API

<SymbolDoc name="Pill" fileName="/preview-react/" />