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, therefore it's default variant is `default`. 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-how-to-customize-styles--docs)
or view the example below.

<ExampleCodeBlock code={CustomStyles} />

## Component API

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