Jump to Navigation
Skip to Content
Component Blueprints

Pills

Lightning Component
  • HTML/CSS:Dev Ready
  • Layout:Desktop Only

Sections

A pill represents an object that can be viewed with or without an icon.
Pill Label

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 classname of slds-pill. You need an <a> inside of the span with the slds-pill_link class. The <a> will get the classname 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 classname 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).

Base#

Pill Label
<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>
  <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
    </svg>
    <span class="slds-assistive-text">Remove</span>
  </button>
</span>

Examples#

With Icon#

Pill Label
<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">
        <use xlink:href="/assets/icons/standard-sprite/svg/symbols.svg#account"></use>
      </svg>
      <span class="slds-assistive-text">Account</span>
    </span>
  </span>
  <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>
  <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
    </svg>
    <span class="slds-assistive-text">Remove</span>
  </button>
</span>

With Avatar#

Person namePill Label
<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" />
    </span>
  </span>
  <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>
  <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
    </svg>
    <span class="slds-assistive-text">Remove</span>
  </button>
</span>

Pill with Container#

Pill LabelPill LabelPill Label
<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>
    </a>
    <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
      <svg class="slds-button__icon" aria-hidden="true">
        <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
      </svg>
      <span class="slds-assistive-text">Remove</span>
    </button>
  </span>
  <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>
    <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
      <svg class="slds-button__icon" aria-hidden="true">
        <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
      </svg>
      <span class="slds-assistive-text">Remove</span>
    </button>
  </span>
  <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>
    <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
      <svg class="slds-button__icon" aria-hidden="true">
        <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
      </svg>
      <span class="slds-assistive-text">Remove</span>
    </button>
  </span>
</div>

States#

Error#

WarningPill Label
<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">
        <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#error"></use>
      </svg>
      <span class="slds-assistive-text">Warning</span>
    </span>
  </span>
  <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>
  <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
    <svg class="slds-button__icon" aria-hidden="true">
      <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
    </svg>
    <span class="slds-assistive-text">Remove</span>
  </button>
</span>

Truncated#

The pills component will respect the width of its parent and truncate if necessary.

Pill label that is longer than the area that contains it
<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>
    </a>
    <button class="slds-button slds-button_icon slds-button_icon slds-pill__remove" title="Remove">
      <svg class="slds-button__icon" aria-hidden="true">
        <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
      </svg>
      <span class="slds-assistive-text">Remove</span>
    </button>
  </span>
</div>

Listbox Of Pill Options#

<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">
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
    <li class="slds-listbox-item" role="presentation">
      <span class="slds-pill" role="option" aria-selected="true">
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
  </ul>
</div>

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 focusabled 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">
  <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">
        <span class="slds-icon_container slds-icon-standard-account slds-pill__icon_container" title="Account">
          <svg class="slds-icon" aria-hidden="true">
            <use xlink:href="/assets/icons/standard-sprite/svg/symbols.svg#account"></use>
          </svg>
          <span class="slds-assistive-text">Account</span>
        </span>
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
    <li class="slds-listbox-item" role="presentation">
      <span class="slds-pill" role="option" aria-selected="true">
        <span class="slds-icon_container slds-icon-standard-case slds-pill__icon_container" title="Case">
          <svg class="slds-icon" aria-hidden="true">
            <use xlink:href="/assets/icons/standard-sprite/svg/symbols.svg#case"></use>
          </svg>
          <span class="slds-assistive-text">Case</span>
        </span>
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
  </ul>
</div>

With Avatar#

<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">
        <span class="slds-avatar slds-avatar_x-small slds-pill__icon_container">
          <img alt="Person name" src="/assets/images/avatar2.jpg" title="User avatar" />
        </span>
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
    <li class="slds-listbox-item" role="presentation">
      <span class="slds-pill" role="option" aria-selected="true">
        <span class="slds-avatar slds-avatar_x-small slds-pill__icon_container">
          <img alt="Person name" src="/assets/images/avatar2.jpg" title="User avatar" />
        </span>
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
  </ul>
</div>

Layout#

Bare#

<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">
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
    <li class="slds-listbox-item" role="presentation">
      <span class="slds-pill slds-pill_bare" role="option" aria-selected="true">
        <span class="slds-pill__label" title="Full pill label verbiage mirrored here">Pill Label</span>
        <span class="slds-icon_container slds-pill__remove" title="Remove">
          <svg class="slds-icon slds-icon_x-small slds-icon-text-default" aria-hidden="true">
            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
          </svg>
          <span class="slds-assistive-text">Press delete or backspace to remove</span>
        </span>
      </span>
    </li>
  </ul>
</div>

Overview of CSS Classes

Selector.slds-pill
Summary

Initializes pill

Supportdev-ready
Restrictspan
VariantTrue
Selector.slds-pill_bare
Summary

Modifier that removes border and background from a pill

Restrict.slds-pill
ModifierTrue
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
ModifierTrue
Selector.slds-listbox [role="listbox"]
Summary

A listbox of Pills is a way to display a list of selected options when performing user input

Supportdev-ready
Restrict.slds-pill
VariantTrue

Pills Release Notes

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