Pill

Anatomy

1. Container: Background and stroke element containing all other elements within this component
2. Pill Label: Describes the Pill meaning or input.
3. Icon (Optional): Displayed before the Pill label to provide an additional supporting visual. Icons displayed after the label are reserved for Removable Pills to further convey the action. For Removable Pills, the icon becomes the click or touch target.
4. Counter: Number appearing after the label used to show the count of something.
5. Counter Container: Contrasting background that houses the Counter.
6. Avatar (Optional): Circular graphic or photo that appears to the left of the Pill label.

Usage Guidance

Pills 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 input a section, filter a list or table, or label information to help with scanning and organization.

Pills with Icon or Avatar

• There are considerations specifically for leading and trailing icons.
• 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.
• All trailing elements are reserved for removable Pills and Pills with count. The X icon indicates the expected interaction, and appears after the label to assure the user is aware what is being removed. The count appears after indicating the action is directly related to the count of that label.

Pills that are Removable

• Pills that are removable display the X icon following after the label.
• Removable pills have a smaller, more specific focus state and click target to be more intentional about its action and to avoid unintended removal of a Pill.
• Pills are aligned either left or right and the flow of the removal will move existing Pills towards that alignment. If a Pill is removed, there should be a way for the user to add the Pill again.

Pills Used as a Filter

• Filters appearing as a Pill allow for the user to scan and organize their filters more easily.
• Pills fit the type of filter into a small space and allows users to quickly see if the filter is applied and/or remove it.
• Pills add progressive disclosure to your filters by increasing learnability and reducing filter errors.

Responsive Treatment

Pills should fill their container, inline. For smaller screens and smaller containers wrap Pills so they stack to multiple lines when necessary.

When To Use

• To show and label selected inputs that can be added and removed.
• Pills are meant for displaying in a small space as a group. Use them to communicate labels, selections, and categories.
• Pills can increase the amount of visual noise on a page so use them in moderation.
• Pills can be used to input complex information in a compact Form Field. Input Pills allow users to verify input by converting content or text into a Pill. They can produce suggested responses, such as in a Workday Prompt.

When To Use Something Else

• For static labels that communicate a status use the Status Indicator component.
• For actions that affect anything else use a Button. Buttons are expected to appear consistently and with familiar calls to action, Pills should appear dynamically as a group of multiple interactive elements.
• For labels that don’t appear in multiples and in a group, consider using simple body text or a header.
• If you have more content than a simple label to display, consider using simple body text or a header.

Examples

Pills 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 to all SystemIconProps.

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.

Regina Skeltor

Regina Skeltor

Show Code

Count

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

Read Only

If the Pill has variant='readOnly', it will look like a read-only Pill. This is a non-interactive element that is used to display information.

NOTE: maxWidth measures the width of the Pill.Label (or text) and not the width of the entire Pill. By default, this maxWidth is set to 200px and the text will be truncated with an ellipsis and render an OverflowTooltip on hover and focus. This max width can be changed by providing a maxWidth prop on the Pill.

Removable Pills

Removable Pills 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.

<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

Pink Shirts

Carolyn Grimaldi

This is a category that should not exist because it is too long

Show Code

List of Pills

Pills 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.

Component API

<Pill variant="readOnly">This is a read only</Pill>

<Pill onClick={() => console.log('clicked')}>
  <Pill.Avatar /> Regina Skeltor
</Pill>

<Pill variant="removable">
  <Pill.Avatar /> Regina Skeltor
  <Pill.IconButton onClick={() => console.log('clicked')} />
</Pill>

<Pill variant="removable">
  Shoes
  <Pill.IconButton onClick={() => console.log('handle remove')} />
</Pill>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Pill variant="removable">
  <Pill.Avatar url={avatarUrl} />
  Regina Skeltor
  <Pill.IconButton onClick={() => console.log('handle remove')} />
</Pill>

<Pill onClick={() => console.warn('clicked')}>
  Shoes
  <Pill.Count>30</Pill.Count>
</Pill>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Pill onClick={() => console.warn('clicked')}>
  <Pill.Icon />
  <Pill.Label>Regina Skeltor</Pill.Label>
</Pill>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

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

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Pill variant="readOnly">
  <Pill.Label>Read-only</Pill.Label>
</Pill>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

Accessibility Guidelines

• If the content exceeds the max-width, an ellipses must appear to communicate overflow. Full content will appear on hover or focus within a Tooltip.
• Pills are intended to be placed on white UI backgrounds. Consider contrast requirements when placing elsewhere.
• The click and touch targets for Pills are expanded beyond the Pill container to better support responsive, touch screen devices.
• Removable Pills have an intentionally small, more specific touch target to avoid accidental Pill removal.
• Pill names must be clear and distinctive from one another. Avoid using many Pills on the page with generic identical names. This places additional burden on users to correctly understand the surrounding context for each of the identical pills on the screen.
• When a Pill is disabled, it typically will not appear in the keyboard focus order. However, this can make it more difficult for users to discover, especially with reduced contrast. If a disabled Pill is blocking users' progress through a flow, it's be beneficial to add it back into keyboard focus order. Also, when a lengthy, disabled Pill is truncated, then keyboard users will not have access to the full length text if they cannot focus it.
• Screen-readers must announce the entire Pill Label, regardless of width or truncation.

For more accessibility considerations, refer to the Accessibility Guide.

Content Guidelines

• Pill labels should be kept simple, short and concise. They’re great for organizing and providing cues for what’s been selected, but you can’t fit a lot into that space. Max-width is defined by the width of the parent container of the Pill plus padding.
• If the content exceeds the max-width, an ellipses must appear to communicate overflow.
• Full content will appear on hover in a Tooltip. If you have more content than a simple label to display, use another component recommended above under guidelines.
• When writing content for Pill Labels, refer to our Content Style Guide.