Display Pill Group
A Display Pill Group is a set of Pills used to visually represent a collection of entities outside of form-based UIs.
const DisplayPillGroupExample = () => {return (<DisplayPillGroup aria-label="Products:"><DisplayPill>Voice</DisplayPill><DisplayPill href="https://google.com">Studio</DisplayPill><DisplayPill><SMSCapableIcon decorative size="sizeIcon10" />SMS</DisplayPill><DisplayPill href="https://google.com"><MMSCapableIcon decorative size="sizeIcon10" />MMS</DisplayPill><DisplayPill><Avatar size="sizeIcon10" name='Customer' src="/images/avatars/avatar4.png" />Customer</DisplayPill><DisplayPill href="https://google.com"><Avatar size="sizeIcon10" name='Agent' icon={AgentIcon} />Agent</DisplayPill></DisplayPillGroup>);}render(<DisplayPillGroupExample />)
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.
const BasicDisplayPillGroup = () => {return (<DisplayPillGroup><DisplayPill>Notify</DisplayPill><DisplayPill>Proxy</DisplayPill><DisplayPill><ProductVerifyIcon decorative size="sizeIcon10" />Verify</DisplayPill><DisplayPill><ProductInterconnectIcon decorative size="sizeIcon10" />Interconnect</DisplayPill><DisplayPill>Transcriptions</DisplayPill><DisplayPill>Chat</DisplayPill></DisplayPillGroup>);}render(<BasicDisplayPillGroup />)
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.
const LinkedDisplayPillGroup = () => {return (<DisplayPillGroup aria-label="Products:"><DisplayPill href="https://google.com">Authy</DisplayPill><DisplayPill href="https://google.com"><ProductPhoneNumbersIcon decorative size="sizeIcon10" />Phone Numbers</DisplayPill><DisplayPill href="https://google.com"><ProductFrontlineIcon decorative size="sizeIcon10" />Frontline</DisplayPill><DisplayPill href="https://google.com"><Avatar size="sizeIcon10" name='Customer' src="/images/avatars/avatar4.png" />Customer</DisplayPill><DisplayPill href="https://google.com"><Avatar size="sizeIcon10" name='Agent' icon={AgentIcon} />Agent</DisplayPill></DisplayPillGroup>);}render(<LinkedDisplayPillGroup />)
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.
const DisplayPillGroupExample = () => {return (<DisplayPillGroup aria-label="Products:"><DisplayPill href="https://www.twilio.com/segment-hello"><ProductSegmentIcon decorative size="sizeIcon10" />Segment</DisplayPill><DisplayPill>Flex</DisplayPill><DisplayPill href="https://sendgrid.com/">SendGrid</DisplayPill><DisplayPill><LogoTwilioIcon decorative size="sizeIcon10" />Twilio</DisplayPill></DisplayPillGroup>);}render(<DisplayPillGroupExample />)
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.
const TruncateDisplayPillGroup = () => {return (<DisplayPillGroup aria-label="Products:"><DisplayPill><ProductInternetOfThingsIcon decorative size="sizeIcon10" /><Box maxWidth="size10"><Truncate title="Internet of Things">Internet of Things</Truncate></Box></DisplayPill><DisplayPill><ProductMarketingCampaignsIcon decorative size="sizeIcon10" /><Box maxWidth="size10"><Truncate title="Marketing Campaigns">Marketing Campaigns</Truncate></Box></DisplayPill><DisplayPill><ProductCodeExchangePartnerIcon decorative size="sizeIcon10" /><Box maxWidth="size10"><Truncate title="CodeExchange Partner">CodeExchange Partner</Truncate></Box></DisplayPill><DisplayPill><ProductEngagementIntelligencePlatformIcon decorative size="sizeIcon10" /><Box maxWidth="size10"><Truncate title="Engagement Intelligence Platform">Engagement Intelligence Platform</Truncate></Box></DisplayPill></DisplayPillGroup>);};render(<TruncateDisplayPillGroup />)
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.
const AvatarDisplayPillGroupExample = () => {return (<DisplayPillGroup aria-label="People:"><DisplayPill href="https://google.com"><Avatar size="sizeIcon10" name='Customer' src="/images/avatars/avatar4.png" />Customer</DisplayPill><DisplayPill href="https://google.com"><Avatar size="sizeIcon10" name='Agent' icon={AgentIcon} />Agent</DisplayPill></DisplayPillGroup>);}render(<AvatarDisplayPillGroupExample />)
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.
const IconDisplayPillGroup = () => {return (<DisplayPillGroup aria-label="Products:"><DisplayPill><ProductMessagingIcon decorative size="sizeIcon10" />Messaging</DisplayPill><DisplayPill><ProductBillingIcon decorative size="sizeIcon10" />Billing</DisplayPill><DisplayPill><ProductLookupIcon decorative size="sizeIcon10" />Lookup</DisplayPill><DisplayPill><ProductConversationsIcon decorative size="sizeIcon10" />Conversations</DisplayPill></DisplayPillGroup>);};render(<IconDisplayPillGroup />)
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.