lightning:pill

A pill represents an existing item in a database, as opposed to user-generated freeform text.

A lightning:pill component represents an item, such as an account name or case number, and the text label is wrapped by a rounded border. 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 inherits styling from pills in the Lightning Design System.

Use the class attribute to apply additional styling.

This example creates a basic pill.

<aura:component>
    <lightning:pill label="Pill Label" href="/path/to/some/where" onremove="{! c.handleRemove }"/>
</aura:component>

Pills have two clickable elements: the text label and the remove button. Both 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 on the pill triggers the onremove handler and then the onclick handler. These event handlers are optional.

To prevent the onclick handler from running, call event.preventDefault() in the onremove handler.

<aura:component>
    <lightning:pill label="hello pill" onremove="{! c.handleRemoveOnly }" onclick="{! c.handleClick }"/>
</aura:component>
({
    handleRemoveOnly: function (cmp, event) {
        event.preventDefault();
        alert('Remove button was clicked!');
    },
    handleClick: function (cmp, event) {
        // this won't run when you click the remove button 
        alert('The pill was clicked!');
    }
})
Inserting an Image

A pill can contain an image, such as an icon or avatar, which represents the type of object. To insert an image in the pill, use the media attribute.

<aura:component>
    <lightning:pill label="Pill Label" href="/path/to/some/where">
        <aura:set attribute="media">
            <lightning:icon iconName="standard:account"  alternativeText="Account"/>
        </aura:set>
    </lightning:pill>
</aura:component>
Usage Considerations

A pill can display 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 a pill that contains an error. Setting hasError to true inserts a warning icon in the pill and change the border to red. Providing your own image in this context has no effect on the pill.

Accessibility

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.

Attributes

Attribute Name Attribute Type Description Required?
body Component[] The body of the component. In markup, this is everything in the body of the tag.
class String A CSS class for the outer element, in addition to the component's base classes.
hasError Boolean Specifies whether the pill has errors. The default is false.
href String The URL of the page that the link goes to.
label String The text label that displays in the pill. Yes
media Component[] The icon or figure that's displayed next to the textual information.
name String The name for the pill. This value is optional and can be used to identify the pill in a callback.
onclick Action The action triggered when the button is clicked.
onremove Action The action triggered when the pill is removed.
title String Displays tooltip text when the mouse moves over the element.