Pill

A lightning:pill component represents an item, such as an account name or case number. By default, pills are rendered with a remove button. They are useful for displaying read-only text that can be added and removed on demand, for example, a list of email addresses or a list of keywords.

This component implements styling from pills in the Lightning Design System.

Use the class attribute to apply additional styling.

This example creates a basic pill with a link.

1<aura:component>
2  <lightning:pill
3    label="Pill Label"
4    href="https://www.example.com"
5    onremove="{! c.handleRemove }"
6  />
7</aura:component>

URLs without a protocol use the host domain’s protocol. For example, www.example.com is prefixed with https:// if the host domain’s protocol is https://.

A pill can contain an icon or avatar to represent the type of object. To insert an icon or avatar in the pill, use the media attribute to include your lightning:icon or lightning:avatar component.

Insert an icon on the pill using lightning:icon. For more information, see lightning:icon.

1<aura:component>
2  <lightning:pill label="Pill Label" href="https://www.example.com">
3    <aura:set attribute="media">
4      <lightning:icon iconName="standard:account" alternativeText="Account" />
5    </aura:set>
6  </lightning:pill>
7</aura:component>

Insert an avatar on the pill using lightning:avatar. For more information, see lightning:avatar.

1<aura:component>
2  <lightning:pill label="Pill Label" href="https://www.example.com">
3    <aura:set attribute="media">
4      <lightning:avatar
5        src="/docs/component-library/app/images/examples/avatar2.jpg"
6        fallbackIconName="standard:user"
7        variant="circle"
8        alternativeText="User avatar"
9      />
10    </aura:set>
11  </lightning:pill>
12</aura:component>

A pill has three clickable elements.

• The optional icon or avatar
• The text label
• The remove button

All three elements trigger the onclick handler. If you provide an href value, clicking the text label triggers the onclick handler and then takes you to the provided path.

Clicking the remove button (X) on the pill fires the remove event and then the click event. Use the optional onremove and onclick handlers to remove the pill and perform an action. You must hide or remove the pill on your own using the onremove handler, as shown in the example below. If you don’t specify a pill removal behavior, clicking the remove button doesn’t have a visible effect.

When an href value is present, clicking the text label navigates to a link, but clicking the icon or avatar doesn’t. To prevent your browser from navigating to a link when you click a pill’s label, call event.preventDefault() in the onclick handler.

This example hides a pill when the remove button is clicked.

1<aura:component>
2  <lightning:pill
3    label="hello pill"
4    onremove="{! c.handleRemoveOnly }"
5    onclick="{! c.handleClick }"
6  />
7</aura:component>

To prevent navigating to the link when the remove button is clicked, call event.preventDefault() in the onremove handler. The click event is still fired when you click the text label. However, calling event.preventDefault() in the onremove handler prevents the click event from firing when you click the remove button.

1({
2  handleRemoveOnly: function (cmp, event) {
3    event.preventDefault();
4    alert("Remove button was clicked!");
5  },
6  handleClick: function (cmp, event) {
7    // this won't run when you click the remove button
8    alert("The pill was clicked!");
9  },
10});

Display a pill in an error state when the containing text doesn’t match a pre-defined collection of items, such as when an email address is invalid or a case number doesn’t exist.

Use the hasError attribute to denote an error on a pill. Setting hasError to true inserts an error icon next to the label and changes the label text to red. Providing an icon or avatar in this context has no effect on the pill; the error icon is still displayed.

1<aura:component>
2  <lightning:pill
3    label="Pill Label"
4    href="https://www.example.com"
5    hasError="true"
6  />
7</aura:component>

Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.

To create more than one pill, use the lightning:pillContainer component, which gives you access to the pill array via the itemremove event.

Specifying a target to change where the link should open is not supported. The link opens on the same tab or window. To create a URL that navigates to another page in Salesforce, use lightning:navigation.

When using lightning:avatar, use the alternativeText attribute to describe the avatar, such as a user’s initials or name. This description provides the value for the alt attribute in the img HTML tag.

When using lightning:icon, use the alternativeText attribute to describe the icon. For example, specify “Account” instead of “Pill icon”. This description is used as assistive text on the pill.

Press the Tab key to move focus to a pill with a link, and tab again to move focus to the remove button. To remove a pill, press the Enter key when you tab to the remove button. You can define your own behavior to remove the pill from view, such as using the onremove handler shown in Interacting with Pills. To navigate to the target of a link on a pill, press the Enter key when the focus is on the pill.