About Pills#

To create a pill, apply the .slds-pill class on a <span>.

Depending on your context, you will either need a base pill (linked or unlinked), or a pill option inside of a listbox. Note that a linked pill should not be used as 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 and unlinked pills, a <span> with the class name of slds-pill__label should contain the string of text describing the pill object.

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 Salesforce native mobile applications. 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="#" 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#

Pill LabelRemove

• Show Code

<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="#" 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="#" 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#

<div class="slds-pill_container">
  <div class="slds-assistive-text" id="listbox-pill-default">Press delete or backspace to remove</div>
  <ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal" aria-describedby="listbox-pill-default">
    <li class="slds-listbox-item" role="presentation">

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.

Note that a linked pill should not be used as a pill option inside of a listbox

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 or Delete key when focused on a pill

Notable attributes

• role="listbox" is placed on the ul
• aria-label is applied to listbox to describe what the list of options are to the user
• aria-orientation="horizontal" is applied to the listbox to describe the left to right direction of the pills
• role="presentation" is placed on the li elements
• role="option" is placed on the slds-pill elements
• aria-selected="true" is applied to all option elements, this is because they have all be selected
• tabindex="0" is applied to the option that is in focus last. By default it is placed on the first option

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 list
• Left arrow key will move focus to the previous pill in the list
• Left arrow key when on the first option should cycle user focus to the last option
• Right arrow key when on the last option should cycle user focus to the first option
• Delete or Backspace key when focused on an option should remove that option. Focus should then be placed on the nearest option
  • When on the last option, place user focus on the previous option
  • When on the first option, place user focus on the next option
  • When on the only option, place user focus on the listbox or any input element the option might be associated with

Examples#

With Icon#

<div class="slds-pill_container">
  <div class="slds-assistive-text" id="listbox-pill-with-icon">Press delete or backspace to remove</div>
  <ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal" aria-describedby="listbox-pill-with-icon">
    <li class="slds-listbox-item" role="presentation">

With Avatar#

<div class="slds-pill_container">
  <div class="slds-assistive-text" id="listbox-pill-with-avatar">Press delete or backspace to remove</div>
  <ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal" aria-describedby="listbox-pill-with-avatar">
    <li class="slds-listbox-item" role="presentation">

Layout#

Bare#

<div class="slds-pill_container">
  <div class="slds-assistive-text" id="listbox-pills-bare">Press delete or backspace to remove</div>
  <ul class="slds-listbox slds-listbox_horizontal" role="listbox" aria-label="Selected Options:" aria-orientation="horizontal" aria-describedby="listbox-pills-bare">
    <li class="slds-listbox-item" role="presentation">

Styling Hooks Overview#