@workday/canvas-kit-docs
Version:
Documentation components of Canvas Kit components
111 lines (70 loc) • 3.55 kB
text/mdx
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';
`Pill`s are static or interactive indicators that allow users to input, filter, or label
information.
```sh
yarn add @workday/canvas-kit-preview-react
```
`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} />
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} />
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} />
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 `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} />
`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} />
`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} />
<SymbolDoc name="Pill" fileName="/preview-react/" />