Pills
- HTML/CSS:Dev Ready
- Layout:Desktop Only
Sections
You are currently viewing a sandbox preview version of Spring ’20 | Go back to Summer ’20
About Pills#
To create a pill, apply the .slds-pill
class on a <span>
.
Depending on your context, you will either need a linked pill or a pill option inside of a listbox.
For linked pills, a modifier class of slds-pill_link
needs to be added to the existing <span>
with the class name of slds-pill
. You need an <a>
inside of the span with the slds-pill_link
class. The <a>
will get the class name of slds-pill__action
. This will treat the interactions differently from an unlinked pill option inside of a listbox.
For both linked pills and unlinked pill options, a <span>
with the class name of slds-pill__label
should contain the string of text describing the pill object.
Note, that a linked pill should not be used as a pill option inside of a listbox.
Additionally, a pill can have an icon or image that sits to the left-hand side of the .slds-pill__label
. That icon or image should receive the class .slds-pill__icon_container
.
You may also want the functionality to remove the pill as a selection. An "X" icon is normally used and will sit to the right-hand side of the .slds-pill__label
. That icon should receive the class .slds-pill__remove
.
A .slds-pill_container
can be used as a visual container for multiple pill(s).
Mobile#
On mobile devices, such as phones and other devices that have touch as the primary method of interaction, pills will have an increased size to accommodate tapping with a finger instead of the more precise mouse cursor.
Below is a live example of what to expect in that context. No code changes are needed in the Salesforce platform context as this change occurs automatically in the appropriate context. For those users not on the Salesforce platform, these modifications will occur automatically when the secondary touch stylesheet is loaded and the device has touch as the primary method of interaction.
Base#
<span class="slds-pill slds-pill_link">
<a href="javascript:void(0);" class="slds-pill__action" title="Full pill label verbiage mirrored here">
<span class="slds-pill__label">Pill Label</span>
</a>
Examples#
With Icon#
<span class="slds-pill slds-pill_link">
<span class="slds-pill__icon_container">
<span class="slds-icon_container slds-icon-standard-account" title="Account">
<svg class="slds-icon" aria-hidden="true">
With Avatar#
<span class="slds-pill slds-pill_link">
<span class="slds-pill__icon_container">
<span class="slds-avatar slds-avatar_circle" title="User avatar">
<img alt="Person name" src="/assets/images/avatar2.jpg" title="User avatar" />
Pill with Container#
<div class="slds-pill_container">
<span class="slds-pill slds-pill_link">
<a href="javascript:void(0);" class="slds-pill__action" title="Full pill label verbiage mirrored here">
<span class="slds-pill__label">Pill Label</span>
States#
Error#
<span class="slds-pill slds-pill_link slds-has-error">
<span class="slds-pill__icon_container">
<span class="slds-icon_container" title="Error">
<svg class="slds-icon slds-icon-text-error" aria-hidden="true">
Truncated#
The pills component will respect the width of its parent and truncate if necessary.
<div class="slds-pill_container">
<span class="slds-pill slds-pill_link">
<a href="javascript:void(0);" class="slds-pill__action" title="Pill label that is longer than the area that contains it">
<span class="slds-pill__label">Pill label that is longer than the area that contains it</span>
Listbox Of Pill Options#
- Pill LabelPress delete or backspace to remove
- Pill LabelPress delete or backspace to remove
<div class="slds-pill_container">
<ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal">
<li class="slds-listbox-item" role="presentation">
<span class="slds-pill" role="option" tabindex="0" aria-selected="true">
A Listbox of Pills is a way to display a list of selected options when performing user input, usually from a multi-select Combobox, Lookup or Picklist.
Accessibility#
Interaction requirements
- Only 1 focused Pill per set of Pills
- The remove button must not be a focusable element, but can be clickable
- Delete with a keyboard is performed with the
Backspace
orDelete
key when focused on a pill
Notable attributes
role="listbox"
is placed on theul
aria-label
is applied tolistbox
to describe what the list of options are to the useraria-orientation="horizontal"
is applied to thelistbox
to describe the left to right direction of the pillsrole="presentation"
is placed on theli
elementsrole="option"
is placed on theslds-pill
elementsaria-selected="true"
is applied to alloption
elements, this is because they have all be selectedtabindex="0"
is applied to theoption
that is in focus last. By default it is placed on the firstoption
Keyboard navigation
- The first
option
in the list will be take user focus initially, when tabbed to Right
arrow key will move focus to the next pill in the listLeft
arrow key will move focus to the previous pill in the listLeft
arrow key when on the firstoption
should cycle user focus to the lastoption
Right
arrow key when on the lastoption
should cycle user focus to the firstoption
Delete
orBackspace
key when focused on anoption
should remove thatoption
. Focus should then be placed on the nearestoption
- When on the last
option
, place user focus on the previousoption
- When on the first
option
, place user focus on the nextoption
- When on the only
option
, place user focus on thelistbox
or anyinput
element theoption
might be associated with
- When on the last
Examples#
With Icon#
- AccountPill LabelPress delete or backspace to remove
- CasePill LabelPress delete or backspace to remove
<div class="slds-pill_container">
<ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal">
<li class="slds-listbox-item" role="presentation">
<span class="slds-pill" role="option" tabindex="0" aria-selected="true">
With Avatar#
Pill LabelPress delete or backspace to remove
Pill LabelPress delete or backspace to remove
<div class="slds-pill_container">
<ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal">
<li class="slds-listbox-item" role="presentation">
<span class="slds-pill" role="option" tabindex="0" aria-selected="true">
Layout#
Bare#
- Pill LabelPress delete or backspace to remove
- Pill LabelPress delete or backspace to remove
<div class="slds-pill_container">
<ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal">
<li class="slds-listbox-item" role="presentation">
<span class="slds-pill slds-pill_bare" role="option" tabindex="0" aria-selected="true">
Overview of CSS Classes#
- Selector
- The CSS class being referred to.
- Summary
- A description of what the class does.
- Support
- Whether the class name is dev-ready (meaning it's fully vetted and tested and safe to use) or prototype (which means it's not fully vetted yet).
- Restrict
- The selector that the class name is allowed to be used on.
- Variant
- The base level pattern for a component. A variant can be extended to create another variant of that component, for example, a stateful button is a derivative of the base button.
- Modifier
- A single class that can be added to an HTML element of a component to modify its output. Typically these will be colors, sizing and positioning.
Selector | .slds-pill |
---|---|
Summary | Initializes pill |
Support | dev-ready |
Restrict | span |
Variant | True |
Selector | .slds-pill_bare |
---|---|
Summary | Modifier that removes border and background from a pill |
Restrict | .slds-pill |
Modifier | True |
Selector | .slds-pill__label |
---|---|
Summary | Line of text inside a pill |
Restrict | .slds-pill a, .slds-pill span |
Selector | .slds-pill__icon_container |
---|---|
Summary | Initializes pill icon or avatar that sits to the left of the label |
Restrict | .slds-pill span |
Selector | .slds-pill__remove |
---|---|
Summary | Initializes remove icon in pill that sits to the right of the label |
Restrict | .slds-pill button, .slds-pill span |
Selector | .slds-pill_link |
---|---|
Summary | Creates a pill with a hyperlink |
Restrict | .slds-pill |
Selector | .slds-pill__action |
---|---|
Summary | Actionable element inside of pill with hyperlink |
Restrict | .slds-pill_link a |
Selector | .slds-has-error |
---|---|
Summary | Pill error styles |
Restrict | .slds-pill |
Modifier | True |
Selector | .slds-listbox [role="listbox"] |
---|---|
Summary | A listbox of Pills is a way to display a list of selected options when performing user input |
Support | dev-ready |
Restrict | .slds-pill |
Variant | True |
Pills Release Notes
2.11.7
Added
- Added documentation and examples for mobile/touch context
2.10.0
Changed
- For touch devices:
- Increase tap target height of
.slds-pill
to$height-tappable-small
(2rem) and change horizontal padding to$spacing-small
(0.75rem) - Update spacing between pills to
$spacing-xx-small
(0.25rem) - Set padding of pill container to
$spacing-xx-small
(0.25rem) - Set
font-size
of.slds-pill__label
to$font-size-4
(0.875rem) - Update the padding of
.slds-pill__action
- Adjust the positioning of the icon inside a pill after padding updates
- Increase tap target height of