A Display Pill Group represents a collection of static objects. Display Pills are static text and should be used where Pills aren’t in a state where they’re actively being modified.
A label helps explain what a collection of data objects represents. Set a non-visual label on a Display Pill Group using aria-label.
A linked Display Pill is a focusable element and a single tab stop to a keyboard user. Once a user focuses on a linked Display Pill, pressing the enter key will open the link.
Display Pill Group creates a list of static items, whereas Form Pill Group creates a list from which a user may select items.
Use the table below to get a better understanding of when to use Display Pill or Form Pill.
| Functionality | Display Pill | Form Pill |
|---|---|---|
| Used to view data | ||
| Uses List, List Item semantic | ||
| Pills can link to a page | ||
| Used to edit data in a form | ||
| Uses Listbox, Option semantic | ||
| Provides advanced keyboard navigation | ||
| Pills can be selected | ||
| Pills can perform an action | ||
| Pills can be dismissed |
Use a Basic Display Pill to display read-only text, such as a list of email addresses or keywords.
A Display Pill can have an optional Avatar or Icon. Use no more than one icon before or after the text.
A Display Pill can link to other pages. This can be useful when the entity the pill represents has its own detail page. To do so, pass an href prop to the Display Pill.
When provided with an href the DisplayPill will render itself as an HTML Anchor element, and will respond to any anchor-based events and accept any event handlers.
A Display Pill Group wraps a collection of basic and linked Display Pills with a common group component.
DisplayPillGroup takes DisplayPills as children. Don’t place any other type of child component directly inside of a DisplayPillGroup.
Pill text should never wrap to the next line. If the text length is longer than the max width of the pill group’s container, consider moving the Pill to a new row or use Truncate to truncate the Display Pill text.
A Display Pill can have an optional Avatar. Considering the size of a Display Pill, it is recommended to use either an image or icon within an Avatar, and to avoid using initials as some initials may get cut off if the characters are particularly wide.
We recommend placing the Avatar ahead of the pill text. Use no more than one before or after the text.
A Display Pill can have an optional Icon. We recommend placing the Icon ahead of the pill text. Use no more than one before or after the text.
Do
Use Display Pills in non-editable situations to represent a collection of similar objects.
Don't
Don’t use Display Pills inside of a form or when editing a collection of data. Use a Multi-select Combobox or Form Pill Group instead.
Do
Use Display Pills to display a list of objects, usually nouns, such as email addresses or keywords.
Don't
Don’t use Display Pills to highlight an attribute of an object for quick identification. Consider using a Badge instead.
Do
Only pass DisplayPill as a direct descendent of a DisplayPillGroup.
Don't
Don’t pass DisplayPillGroup in any other component type, and do not wrap DisplayPill in any other component of the DOM element.