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>

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

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

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

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

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.

Anatomy

1. Container: Contains all Pill elements
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 touch target.
4. Counter: (Optional) Number appearing after the label used to show the count of something.
5. Counter Container: (Optional) Contrasting background that houses the Counter.
6. Avatar: (Optional): A thumbnail photo or placeholder graphic used to represent a specific user that appears to the left of the pill label.

Interaction States

Pills support Inactive, Pressed, and Disabled States.

Variations

Link

Navigates a user to more details about the contents of the pill.

Additive

Tapping on these pills or the additional tappable padding will add it to a parent container.

Non-Interactive

A non-interactive element used to display information about an object.

Non-interactive pills do not truncate and instead wrap to multiple lines; however, try to keep Pill text as succinct as possible - between 2-7 words or wrap no more than 2 lines.

Removable

Removable Pills display an X icon after the label.

The X icon has its own 48dp tap target that removes the pill from its parent container. The Pill area outside of X icon’s tap target is not interactive.

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.

• Link, Removable, and Additive Pills should not wrap to a second line and instead truncate.
• Non-interactive Pills should not truncate and can wrap to multiple lines.
• The max-width of a pill is 600dp, or up to the screen margins of the device. They should fill their container inline. Pill groups can stack to multiple lines when necessary.
• Use pills in moderation, as they can increase the visual noise of a page.

Pills with Icon or Avatar

• Leading elements, such as icons or avatars, should be descriptive elements that help support the label.
• Trailing elements are reserved for actions in Removable Pills and Pills with count. Removable Pills have a trailing X icon that removes the pill from the UI. Pills with count have a trailing Count Indicator that shows how.

Pills that are Removable

• Pills that are removable display the X icon following after the label.
• Removable pills have an X icon with a 48dp touch target that removes the pill.
• 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 users to scan and organize their filters more easily
• Pills fit the type of filter into a small space to allow users to quickly see if the filter has been applied and/or to remove it.
• Pills add progress disclosure to your filters by increasing learnability and reducing filter errors.

When to Use

• To visually label selected inputs that can be added and removed.
• To communicate multiple labels, selections, and categories in a small space as a group.
• To input a section, filter a list or table, or label information to help with scanning.
• To confirm that a selection or input has been made.

When to Use Something Else

• For static labels that communicate a status, use a Status Indicator.
• 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.

Mobile Guidance

• Ensure a minimum tap target height of 48dp to ensure easy interaction. This means adding an additional 4dp of tappable top and bottom padding to the Pill.
• Account for this interaction buffer by spacing multiple pills with 8dp padding between, above, and below each pill in a group.
• Ensure a minimum tap target area of 48dp for the X icon in removable Pills.

API Documentation

Component Definition

TagStyle

public struct TagStyle: ViewModifier

A text tag for elements that represent an input, attribute, or action.

Properties

tag

@Binding public var tag: TagViewModel

onTap

public var onTap: (() -> Void)?

Methods

init(tag:onTap:)

public init(tag: Binding<TagViewModel>, onTap: (() -> Void)? = nil)

Create an instance of TagStyle.

Parameters

body(content:)

public func body(content: Content) -> some View

Accessibility Guidelines

• If content exceeds the max-width, an ellipses should appear at the end of the text to communicate truncation.
• Pills must exceed a 3:1 contrast ratio against the background color the Pill is placed on. See non-text contrast requirement.
• An additional 4dp of tappable top and bottom padding are added to ensure a minimum tap target area of 48dp.
• X icons in removable pills have a 48dp touch target that removes the pill from the UI.
• Pill names should be distinct from one another. Avoid using many Pills on the same page with similar names as this places additional burden on users to understand the context of each pill.
• Screen readers must announce the entire Pill Label, regardless of width or truncation.

For more accessibility considerations, refer to the Accessibility Guide.

Content Guidelines

• Keep pill labels short and concise.
• Max-width of the pill is defined by the width of its parent container plus padding.
• For link, removable, and additive pills, an ellipses should appear to communicate truncated content.
• Non-interactive pills should never truncate and instead wrap to multiple lines.

When writing content for Pill Labels, refer to our Content Style Guide.

Anatomy

1. Container: Contains all Pill elements
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 touch target.
4. Counter: (Optional) Number appearing after the label used to show the count of something.
5. Counter Container: (Optional) Contrasting background that houses the Counter.
6. Avatar: (Optional): A thumbnail photo or placeholder graphic used to represent a specific user that appears to the left of the pill label.

Interaction States

Pills support Inactive, Pressed, and Disabled States.

Variations

Link

Navigates a user to more details about the contents of the pill.

Additive

Tapping on these pills or the additional tappable padding will add it to a parent container.

Non-Interactive

A non-interactive element used to display information about an object.

Non-interactive pills do not truncate and instead wrap to multiple lines; however, try to keep Pill text as succinct as possible - between 2-7 words or wrap no more than 2 lines.

Removable

Removable Pills display an X icon after the label.

The X icon has its own 48dp tap target that removes the pill from its parent container. The Pill area outside of X icon’s tap target is not interactive.

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.

• Link, Removable, and Additive Pills should not wrap to a second line and instead truncate.
• Non-interactive Pills should not truncate and can wrap to multiple lines.
• The max-width of a pill is 600dp, or up to the screen margins of the device. They should fill their container inline. Pill groups can stack to multiple lines when necessary.
• Use pills in moderation, as they can increase the visual noise of a page.

Pills with Icon or Avatar

• Leading elements, such as icons or avatars, should be descriptive elements that help support the label.
• Trailing elements are reserved for actions in Removable Pills and Pills with count. Removable Pills have a trailing X icon that removes the pill from the UI. Pills with count have a trailing Count Indicator that shows how.

Pills that are Removable

• Pills that are removable display the X icon following after the label.
• Removable pills have an X icon with a 48dp touch target that removes the pill.
• 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 users to scan and organize their filters more easily
• Pills fit the type of filter into a small space to allow users to quickly see if the filter has been applied and/or to remove it.
• Pills add progress disclosure to your filters by increasing learnability and reducing filter errors.

When to Use

• To visually label selected inputs that can be added and removed.
• To communicate multiple labels, selections, and categories in a small space as a group.
• To input a section, filter a list or table, or label information to help with scanning.
• To confirm that a selection or input has been made.

When to Use Something Else

• For static labels that communicate a status, use a Status Indicator.
• 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.

Mobile Guidance

• Ensure a minimum tap target height of 48dp to ensure easy interaction. This means adding an additional 4dp of tappable top and bottom padding to the Pill.
• Account for this interaction buffer by spacing multiple pills with 8dp padding between, above, and below each pill in a group.
• Ensure a minimum tap target area of 48dp for the X icon in removable Pills.

API Documentation

Link Pills

@Composable
fun LinkPillUiComponent(
    modifier: Modifier = Modifier,
    pillText: String = "",
    hasAvatar: Boolean = false,
    hasCounter: Boolean = false,
    count: Int = 0,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    textStyle: TextStyle = WorkdayTheme.canvasTypography.bodyMedium,
    onClick: () -> Unit = {},
    interactionState: InteractionState = InteractionState.Enabled
) {

Parameters

All undocumented parameters are native Android Compose types that can be found in the developer documentation.

Additive Pills

@Composable
fun AdditivePillUIComponent(
    modifier: Modifier = Modifier,
    pillText: String = "",
    hasAvatar: Boolean = false,
    textStyle: TextStyle = WorkdayTheme.canvasTypography.bodyMedium,
    onClick: () -> Unit = {},
    interactionState: InteractionState = InteractionState.Enabled
) {

Parameters

Removable Pills

@Composable
fun RemovablePillUiComponent(
    modifier: Modifier = Modifier,
    pillText: String = "",
    hasAvatar: Boolean = false,
    textStyle: TextStyle = WorkdayTheme.canvasTypography.bodyMedium,
    onClick: () -> Unit = {},
    interactionState: InteractionState = InteractionState.Enabled)
) {

Parameters

Non-Interactive Pills

@Composable
fun NonInteractivePillUiComponent(
    modifier: Modifier = Modifier,
    pillText: String = "",
    textStyle: TextStyle = WorkdayTheme.canvasTypography.bodyMedium,
    interactionSource: MutableInteractionSource = MutableInteractionSource()
) {

Parameters

Accessibility Guidelines

• If content exceeds the max-width, an ellipses should appear at the end of the text to communicate truncation.
• Pills must exceed a 3:1 contrast ratio against the background color the Pill is placed on. See non-text contrast requirement.
• An additional 4dp of tappable top and bottom padding are added to ensure a minimum tap target area of 48dp.
• X icons in removable pills have a 48dp touch target that removes the pill from the UI.
• Pill names should be distinct from one another. Avoid using many Pills on the same page with similar names as this places additional burden on users to understand the context of each pill.
• Screen readers must announce the entire Pill Label, regardless of width or truncation.

For more accessibility considerations, refer to the Accessibility Guide.

Content Guidelines

• Keep pill labels short and concise.
• Max-width of the pill is defined by the width of its parent container plus padding.
• For link, removable, and additive pills, an ellipses should appear to communicate truncated content.
• Non-interactive pills should never truncate and instead wrap to multiple lines.

When writing content for Pill Labels, refer to our Content Style Guide.