Pill Container

A lightning:pillContainer component represents a list of pills in a container that resembles an input field. Use lightning:pillContainer to display a user’s selections when filtering a list, such as from a multi-select picklist.

lightning:pillContainer displays a pill using the lightning:pill, component which can display an icon or avatar next to the text label.

To specify the pills, set the items attribute to an array of values.

By default, all pills in the container are displayed and wrap to additional lines if they can’t fit on one line.

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

1<aura:component>
2  <aura:attribute
3    name="items"
4    type="List"
5    default="[
6                {
7                    label: 'My Pill',
8                    name: 'mypill'
9                },
10                {
11                    type: 'avatar',
12                    label: 'Avatar Pill',
13                    name: 'avatarpill',
14                    href: 'https://www.example.com',
15                    src: '/my/path/avatar.jpg',
16                    fallbackIconName: 'standard:user',
17                    variant: 'circle',
18                    alternativeText: 'User avatar',
19                },
20                {
21                    type: 'icon',
22                    label: 'Icon Pill',
23                    name: 'iconpill',
24                    iconName: 'standard:account',
25                    alternativeText: 'Account',
26                },
27            ]"
28  />
29  <lightning:pillContainer items="{!v.items}" />
30</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.

To create a pill with a link, use the following attribute.

• href: Required. The URL for the link.

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 to use as a fallback when the image fails to load. 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’.

lightning:pillContainer provides two variants: bare and standard (default). They’re visually the same. However, the standard variant renders pills in an unordered list element. For more information, see the Accessibility section.

Clicking the remove button triggers the onitemremove handler.

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

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

1({
2  handleItemRemove: function (cmp, event) {
3    var name = event.getParam("item").name;
4    alert(name + " pill was removed!");
5    // Remove the pill from view
6    var items = cmp.get("v.items");
7    var item = event.getParam("index");
8    items.splice(item, 1);
9    cmp.set("v.items", items);
10  },
11});

Several boolean attributes let you control the layout of pills in the container. These attributes are set to false by default, which makes all pills display and wrap to multiple lines.

• isCollapsible: Determines whether the list of pills can be expanded and collapsed. If isCollapsible is true, isExpanded can determine whether a pill list displays all the pills or one line of pills. If isCollapsible is false or not specified, the isExpanded attribute has no effect regardless of its value.
• isExpanded: Determines whether the full list of pills is shown. Set isCollapsible to true if you want to set isExpanded to expand and collapse the list. If you set isExpanded to false and don’t set isCollapsible to true, the list is expanded.
• singleLine: Specifies that the pill container can display one line of pills. By default, if pills can’t fit on one line, they’re wrapped to additional lines to fit the container. Set singleLine to true to limit pill display to one line. This attribute overrides isCollapsible and isExpanded.

If all pills aren’t displayed, the component shows a text button indicating how many more pills there are. For example, if there are five more pills that aren’t displayed, the text button shows +5 more. The text button fires the focus event when you click it.

To display a long list of pills as collapsed, set isCollapsible to true and optionally set isExpanded to false. Otherwise, pills are displayed expanded.

Use isCollapsible and isExpanded to programmatically expand and collapse the pills.

This example sets isCollapsible to true and uses a button to change the value of isExpanded.

1<aura:component>
2  <aura:attribute
3    name="items"
4    type="List"
5    default="[
6        {
7            label: 'My Pill 1',
8            name: 'mypill1'
9        },
10        {
11            label: 'My Pill 2',
12            name: 'mypill2'
13        },
14        {
15            label: 'My Pill 3',
16            name: 'mypill3'
17        },
18        {
19            label: 'My Pill 4',
20            name: 'mypill4'
21        },
22        {
23            label: 'My Pill 5',
24            name: 'mypill5'
25        },
26        {
27            label: 'My Pill 6',
28            name: 'mypill6'
29        },
30    ]"
31  />
32  <aura:attribute name="isCollapsible" type="boolean" default="false" />
33  <aura:attribute name="isExpanded" type="boolean" default="false" />
34  <div style="width: 600px">
35    <lightning:pillContainer
36      items="{!v.items}"
37      isCollapsible="true"
38      isExpanded="{!v.isExpanded}"
39    >
40    </lightning:pillContainer>
41  </div>
42  <br />
43  <lightning:button onclick="{!c.setExpanded}" label="Expand and Collapse">
44  </lightning:button>
45</aura:component>

The list of pills is initially collapsed. The button expands and collapses the list.

1({
2  setExpanded: function (cmp) {
3    cmp.set("v.isExpanded", !cmp.get("v.isExpanded"));
4  },
5});

If all pills aren’t displayed, the component shows a text button labeled +n more to indicate more pills can be displayed. By default, lightning:pillContainer doesn’t handle the focus event that’s fired when you click the button. You can handle the event to display more pills or write logic to do something else when the button is clicked.

This example sets the pills to be collapsible but not expanded and handles the focus event.

1<aura:component>
2  <aura:attribute
3    name="items"
4    type="List"
5    default="[
6            {
7            //define the pills
8            }
9        ];
10    ]"
11  />
12  <aura:attribute name="isCollapsible" type="boolean" default="true" />
13  <aura:attribute name="isExpanded" type="boolean" default="false" />
14  <div style="width: 600px">
15    <lightning:pillContainer
16      items="{!v.items}"
17      isCollapsible="true"
18      isExpanded="{!v.isExpanded}"
19      onfocus="{!c.handlePillExpansion)"
20    >
21    </lightning:pillContainer>
22  </div>
23</aura:component>

The list of pills is initially collapsed. When there are too many pills to be displayed, the text button labeled +n more displays. The handler for the focus event enables all the pills to display.

1({
2  handlePillExpansion: function (cmp) {
3    cmp.set("v.isExpanded", !cmp.get("v.isExpanded"));
4  },
5});

lightning:pillContainer implements the Pills with Container blueprint in the Salesforce Lightning Design System (SLDS) for the base variant.

lightning:pillContainer implements the Listbox of Pill Options blueprint in the Salesforce Lightning Design System (SLDS) for the standard variant.

By default, lightning:pillContainer renders pills using the standard variant, which uses an unordered list element to display pills. Press the Tab key to focus on the first pill and use the Left Arrow and Right Arrow keys to navigate through the pills. Use the Tab key to navigate to the remove button in a pill with a link. Use arrow keys to navigate between pills. The focus goes to a link if present, otherwise focus goes to the remove button.

The bare variant only supports the Tab key for navigating between focusable elements in the container’s pills. The arrow keys aren’t supported.

On mobile devices, both container variants display pills with the close button as a focusable element for accessibility.

To remove a pill, press Enter or the space bar when the pill’s remove button receives focus. On mobile devices, you can tap the remove button to remove a pill.

For pills with links, use the Tab key or arrow keys to focus on the pill’s link, then press Enter to navigate to the link target. If you don’t navigate away from the pill, tabbing again puts focus on the remove button.