lightning:pillContainer

A list of pills grouped in a container. This component requires API version 42.0 and later.

A lightning:pillContainer component represents a list of pills that contains a label with or without an avatar or icon. By default, pills are rendered with a remove button but you must provide the onitemremove event handler. 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 displays pills using lightning:pill, which supports utility icons from the Lightning Design System. Visit https://lightningdesignsystem.com/icons/#utility to view the utility icons.

lightning:pillContainer inherits styling from pills in the Lightning Design System.

This example creates three pills: a text-only pill, a pill with an avatar, and a pill with an icon.

<aura:component>
    <aura:attribute name="items" type="List" default="[
                {
                    label: 'My Pill',
                    name: 'mypill'
                },
                {
                    type: 'avatar',
                    label: 'Avatar Pill',
                    name: 'avatarpill',
                    src: '/my/path/avatar.jpg',
                    fallbackIconName: 'standard:user',
                    variant: 'circle',
                    alternativeText: 'User avatar',
                },
                {
                    type: 'icon',
                    label: 'Icon Pill',
                    name: 'iconpill',
                    iconName: 'standard:account',
                    alternativeText: 'Account',
                },  
            ]"/>
    <lightning:pillContainer items="{!v.items}" />
</aura:component>

A text-only pill supports the following attributes. These attributes can also be used to create a pill with an avatar or icon.

  • label: Required. The text label that displays in the pill.
  • name: The name for the pill. This value is optional and can be used to identify the pill in a callback.
  • href: The URL of the page the link goes to.

To create a pill with an avatar, use the following attributes.

  • type: The media type. Use avatar.
  • src: Required. The URL of the avatar.
  • fallbackIconName: The Lightning Design System name of the icon used as a fallback when the image fails to load. The initials fallback relies on this for its background color. Names are written in the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to be displayed. Only icons from the standard and custom categories are allowed.
  • variant: Changes the shape of the avatar. Valid values are empty, circle, and square. This value defaults to square.
  • alternativeText: The alternative text used to describe the avatar, which is displayed as hover text on the image.

To create a pill with an icon, use the following attributes.

  • type: The media type. Use icon.
  • iconName: Required. The Lightning Design System name of the icon. Names are written in the format '\utility:down\' where 'utility' is the category, and 'down' is the specific icon to be displayed. Only utility icons can be used in this component.
  • alternativeText: The alternative text used to describe the icon. This text should describe what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'.
Removing Pills

Clicking the remove button triggers the onitemremove handler.

<lightning:pillContainer items="{!v.items}" onitemremove="{!c.handleItemRemove}"/>

You can retrieve the name of the pill that's clicked in the event handler and remove the pill from view.

({
    handleRemove: function (cmp, event) {
        var name = event.getParam("item").name;
        alert(name + ' pill was removed!');
        // Remove the pill from view
        var items = cmp.get('v.items');
        var item = event.getParam("index");
        items.splice(item, 1);
        cmp.set('v.items', items);       
    }    
})

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.
items List An array of items to be rendered as pills in a container.
label String Aria label for the pill container.
onitemremove Action The action triggered when a pill is removed.
singleLine Boolean Whether keep pills in single line.
title String Displays tooltip text when the mouse moves over the element.