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

import React from 'react';

import {Pill} from '@workday/canvas-kit-react/pill';
import {BodyText} from '@workday/canvas-kit-react/text';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const flexStyles = createStyles({
  display: 'flex',
  gap: system.gap.sm,
});

export default () => {
  const [text, setText] = React.useState('');
  return (
    <div>
      <div className={flexStyles}>
        <Pill onClick={() => setText('The first pill is clicked!')}>
          <Pill.Icon aria-label="Add user" />
          <Pill.Label>Regina Skeltor</Pill.Label>
        </Pill>
        <Pill disabled>
          <Pill.Icon aria-label="Add user" />
          <Pill.Label>Regina Skeltor</Pill.Label>
        </Pill>
      </div>
      <BodyText size="medium">{text}</BodyText>
    </div>
  );
};

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.

RS

Regina Skeltor

RS

Regina Skeltor

⚡️ Edit in StackblitzShow Code

// @ts-ignore: Cannot find module error
import React from 'react';

import {Pill} from '@workday/canvas-kit-react/pill';
import {BodyText} from '@workday/canvas-kit-react/text';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

// @ts-ignore: Cannot find module error
import testAvatar from './test-avatar.png';

const flexStyles = createStyles({
  display: 'flex',
  gap: system.gap.sm,
});

export default () => {
  const [text, setText] = React.useState('');
  return (
    <div>
      <div className={flexStyles}>
        <Pill onClick={() => setText('The first pill is clicked!')}>
          <Pill.Avatar name="Regina Skeltor" url={testAvatar} />
          <Pill.Label>Regina Skeltor</Pill.Label>
        </Pill>
        <Pill disabled>
          <Pill.Avatar name="Regina Skeltor" />
          <Pill.Label>Regina Skeltor</Pill.Label>
        </Pill>
      </div>
      <BodyText size="medium">{text}</BodyText>
    </div>
  );
};

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.

import React from 'react';

import {Pill} from '@workday/canvas-kit-react/pill';
import {BodyText} from '@workday/canvas-kit-react/text';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const flexStyles = createStyles({
  display: 'flex',
  gap: system.gap.sm,
});

export default () => {
  const [text, setText] = React.useState('');
  return (
    <div>
      <div className={flexStyles}>
        <Pill onClick={() => setText('The first pill is clicked!')}>
          Shoes
          <Pill.Count>30</Pill.Count>
        </Pill>
        <Pill disabled>
          Shoes
          <Pill.Count>30</Pill.Count>
        </Pill>
      </div>
      <BodyText size="medium">{text}</BodyText>
    </div>
  );
};

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.

import {Pill} from '@workday/canvas-kit-react/pill';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const flexStyles = createStyles({
  display: 'flex',
  gap: system.gap.sm,
});

export default () => (
  <div className={flexStyles} id="read-only-list">
    <Pill variant="readOnly">Read-only</Pill>
    <Pill variant="readOnly" cs={{maxWidth: 150}}>
      Read-only but with super long text in case you want to read a paragraph in a Pill which we
      don't recommend
    </Pill>
  </div>
);

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

A

Carolyn GrimaldiThis is a category that should not exist because it is too long

⚡️ Edit in StackblitzShow Code

import React from 'react';

import {Pill} from '@workday/canvas-kit-react/pill';
import {BodyText} from '@workday/canvas-kit-react/text';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

// @ts-ignore: Cannot find module error
import testAvatar from './test-avatar.png';

const flexStyles = createStyles({
  display: 'flex',
  gap: system.gap.sm,
});

export default () => {
  const [text, setText] = React.useState('');
  return (
    <div>
      <div className={flexStyles}>
        <Pill variant="removable">
          <Pill.Label>Pink Shirts</Pill.Label>
          <Pill.IconButton
            aria-label="Remove"
            onClick={() => setText('The first pill is clicked!')}
          />
        </Pill>
        <Pill variant="removable">
          <Pill.Avatar name="Avatar" url={testAvatar} />
          <Pill.Label>Carolyn Grimaldi</Pill.Label>
          <Pill.IconButton
            aria-label="Remove"
            onClick={() => setText('The second pill is clicked!')}
          />
        </Pill>
        <Pill variant="removable" disabled>
          <Pill.Label>This is a category that should not exist because it is too long</Pill.Label>
          <Pill.IconButton aria-label="Remove" />
        </Pill>
      </div>
      <BodyText size="medium">{text}</BodyText>
    </div>
  );
};

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.

import React from 'react';

import {Pill} from '@workday/canvas-kit-react/pill';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const data = [
  'Shoes',
  'Pants',
  'Dress Shoes',
  'Color',
  'Accessories',
  'Luxury',
  'Casual',
  'Hats',
  'Beanies',
  'Glasses',
  'Jewelry',
];

const flexWrapStyles = createStyles({
  display: 'flex',
  flexWrap: 'wrap',
  gap: system.gap.sm,
});

export default () => {
  const [items, setItems] = React.useState(data);

  return (
    <div className={flexWrapStyles}>
      {items.map((cat, index) => {
        return (
          <Pill key={index} variant="removable">
            <Pill.Label>{cat}</Pill.Label>
            <Pill.IconButton
              aria-label="Remove"
              onClick={() => setItems(items.filter(i => i !== cat))}
            />
          </Pill>
        );
      })}
    </div>
  );
};

Custom Styles

Pill supports custom styling via the cs prop. For more information, check our “How To Customize Styles”  or view the example below.

import {systemIconStencil} from '@workday/canvas-kit-react/icon';
import {Pill, pillCountStencil, pillStencil} from '@workday/canvas-kit-react/pill';
import {createStencil} from '@workday/canvas-kit-styling';
import {base, system} from '@workday/canvas-tokens-web';

const customPillStencil = createStencil({
  base: {
    [pillStencil.vars.background]: base.green600,
    [pillStencil.vars.border]: base.green800,
    [pillStencil.vars.label]: system.color.fg.inverse,
    [systemIconStencil.vars.color]: system.color.fg.inverse,
    [pillCountStencil.vars.backgroundColor]: base.green600,
    [pillCountStencil.vars.borderColor]: base.green600,

    '&:hover, &.hover': {
      [pillStencil.vars.background]: base.green800,
      [pillStencil.vars.label]: system.color.fg.inverse,
      [pillCountStencil.vars.backgroundColor]: base.green800,
      [systemIconStencil.vars.color]: system.color.fg.inverse,
      [pillCountStencil.vars.borderColor]: base.green800,
    },
    '&:active, &.active': {
      [pillStencil.vars.background]: base.green800,
      [pillStencil.vars.label]: system.color.fg.inverse,
      [systemIconStencil.vars.color]: system.color.fg.inverse,
      [pillCountStencil.vars.backgroundColor]: base.green800,
    },
    '&:focus, &.focus, &:focus-visible': {
      [pillStencil.vars.background]: base.green800,
      [pillStencil.vars.label]: system.color.fg.inverse,
      [systemIconStencil.vars.color]: system.color.fg.inverse,
      [pillCountStencil.vars.backgroundColor]: base.green800,
    },
    '&:disabled, &.disabled': {
      [pillStencil.vars.background]: base.green600,
      [pillStencil.vars.label]: system.color.fg.inverse,
      [systemIconStencil.vars.color]: system.color.fg.inverse,
    },
  },
});

export default () => {
  return (
    <div>
      <Pill cs={customPillStencil()}>
        <Pill.Icon aria-label="Add user" />
        <Pill.Label>Custom Pill Color</Pill.Label>
        <Pill.Count>10</Pill.Count>
      </Pill>
    </div>
  );
};

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 aria-label='Remove user' onClick={() => console.log('clicked')} />
</Pill>

<Pill variant="removable">
  Shoes
  <Pill.IconButton aria-label='Remove user' 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} />
   <Pill.Label>Regina Skeltor</Pill.Label>
  <Pill.IconButton aria-label='Remove user' 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 onClick={() => console.warn('clicked')}>
   <Pill.Label>Shoes</Pill.Label>
  <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 aria-label='Add user' />
  <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">
  <Pill.Label>Pink Shirts</Pill.Label>
  <Pill.IconButton aria-label='Remove item' 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 Usage Guidance.
• When writing content for Pill Labels, refer to our Content Style Guide.