--- schema_version: "1" id: a01e7a881d3ecdca529e419e968c644cdbda41245f06339f2c2fbc4b5d1c7599 title: Pill Container collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/pillContainer/lightning-pill-container.md canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-pill-container.html source_site: developer.salesforce.com content_type: documentation content_hash: 7ca89dce62fbd3cd6d539ef53ef5a052032614a6ad5ce673be957154b7c05da1 products: - Lightning Component Reference --- # Pill Container **`lightning-pill-container`** A list of pills grouped in a container. This component requires API version 42.0 and later. **For Use In** Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline ::::::tabset{tabs='["Example", "Develop", "Specifications"]'} :::::tab ::component-playground{component="pillContainer" model="lwc" namespace="lightning"} ::::: :::::tab A `lightning-pill-container` component represents a list of pills in a container that resembles an input field. Use `lightning-pill-container` to indicate a user's selections when filtering a list, such as from a multi-select picklist. `lightning-pill-container` includes pills by using the `lightning-pill` component, which can append an icon or avatar next to the text label. To specify the pills, set the `items` attribute to an array of values in your component's JavaScript. By default, all pills in the container wrap to additional lines if they can't fit on one line. For information about changing the behavior, see [Manage Pill Layout in the Container](#manage-pill-layout-in-the-container). This example creates three pills: a text-only pill, a pill with a link and an avatar, and a pill with an icon. ```html ``` ```javascript import { LightningElement } from "lwc"; export default class PillContainerExample extends LightningElement { items = [ { label: "My Pill", name: "mypill", }, { type: "avatar", label: "Avatar Pill", href: "https://www.example.com", 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", }, ]; } ``` ## Design `lightning-pill-container` implements several designs in the Salesforce Lightning Design System (SLDS). The designs adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use. | | SLDS 1 | SLDS 2 | | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | | **Design** (`base` variant) | [Pills with Container](https://v1.lightningdesignsystem.com/components/pills/#Pill-with-Container) | [Pills with Container](https://www.lightningdesignsystem.com/components/pills/#Pill-with-Container) | | **Design** (`standard` variant) | [Listbox of Pill Options](https://v1.lightningdesignsystem.com/components/pills/#Listbox-Of-Pill-Options) | [Listbox of Pill Options](https://www.lightningdesignsystem.com/components/pills/#Listbox-Of-Pill-Options) | | **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) | ## Usage A text-only pill supports several attributes. Use these attributes to create a pill with an avatar or icon. - `label`: Required. The text label 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 follow the format 'standard:account' where 'standard' is the category, and 'account' is the specific icon to include. 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 appears as hover text on the image. To create a pill with an icon, use these 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 include. Supports utility icons only. - `alternativeText`: The alternative text used to describe the icon. Describe what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'. `lightning-pill-container` 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](#accessibility) section. ## Remove Pills Clicking the remove button triggers the `onitemremove` handler. ```html ``` You can retrieve the name of the pill that's clicked in the event handler and remove the pill from view. ```javascript import { LightningElement, track } from "lwc"; export default class PillContainerRemoveExample extends LightningElement { @track items = [ { 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", }, ]; handleItemRemove(event) { const name = event.detail.item.name; alert(name + " pill was removed!"); const index = event.detail.index; this.items.splice(index, 1); } } ``` ## Manage Pill Layout in the Container Several boolean attributes control the layout of pills in the container. These attributes are set to false by default, which makes pills wrap to multiple lines. - `is-collapsible`: Determines whether the list of pills can be expanded and collapsed. If `is-collapsible` is true, `is-expanded` can determine whether a pill list displays all the pills or one line of pills. If `is-collapsible` is false or not specified, the `is-expanded` attribute has no effect regardless of its value. - `is-expanded`: Determines whether the full list of pills is shown. Set `is-collapsible` to true if you want to set `is-expanded` to expand and collapse the list. If you set `is-expanded` to false and don't set `is-collapsible` to true, the list is expanded. - `single-line`: 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 `single-line` to true to limit pill display to one line. This attribute overrides `is-collapsible` and `is-expanded`. 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 `is-collapsible` to true and optionally set `is-expanded` to false. Otherwise, pills are expanded by default. ### Expand and Collapse Pills Programmatically Use `is-collapsible` and `is-expanded` to programmatically expand and collapse the pills. This example sets `is-collapsible` and uses a button to change the value of `is-expanded`. ```html ``` The list of pills is initially collapsed. The button expands and collapses the list. ```javascript import { LightningElement } from "lwc"; export default class PillContainerCanCollapse extends LightningElement { isExpanded = false; setExpanded(event) { this.isExpanded = !this.isExpanded; } items = [ { //define the pills }, ]; } ``` ### Display All Pills With the `+n more` Button 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-pill-container` 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. ```html ``` The list of pills is initially collapsed. When there are too many pills to show, the text button labeled `+n more` displays. The handler for the `focus` event enables all the pills to display. ```javascript import { LightningElement } from "lwc"; export default class PillContainerMoreButtonExpands extends LightningElement { collapsible = true; expanded = false; handlePillExpansion() { this.expanded = true; } items = [ { //define the pills }, ]; } ``` ## Component Styling Use a combination of variants and utility classes to customize your pills. ### Variants When using a [`lightning-avatar`](/docs/platform/lightning-component-reference/guide/lightning-avatar.html) or [`lightning-icon`](/docs/platform/lightning-component-reference/guide/lightning-icon.html) with the pill, consider the variants on those components. ### Utility Classes To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute. ### Styling Hooks Component styling hooks provide CSS custom properties that use the `--slds-c-*` prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the [SLDS 1 component blueprints](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks. For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide. `lightning-pill-container` renders pills using `lightning-pill`. Use the `--slds-c-pill-*` custom properties on `lightning-pill`. CSS custom properties for pill containers work only with particular `lightning-pill-container` variants for the remove button. | CSS Custom Property | `lightning-pill-container` Variants | | ---------------------------------------- | ----------------------------------- | | `--slds-c-icon-color-background` | `standard` (default) | | `--slds-c-icon-color-foreground-default` | `standard` (default) | | `--slds-c-button-color-background` | `bare` | | `--slds-c-button-color-border` | `bare` | | `--slds-c-button-radius-border` | `bare` | | `--slds-c-button-sizing-border` | `bare` | ## Accessibility By default, `lightning-pill-container` 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. ## Custom Events **`itemremove`** The event fired when a pill is removed. The `itemremove` event returns the following parameters. | Parameter | Type | Description | | --------- | ------ | -------------------------------------- | | item | string | The name of the pill that's removed. | | index | number | The position of the pill in the array. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | ------------------------------------------------------------------------------ | | bubbles | false | This event does not bubble. | | cancelable | true | This event can be canceled. You can call `preventDefault()` on this event. | | composed | false | This event does not propagate outside the template in which it was dispatched. | ::::: :::::tab ::component-specification{component="pillContainer" model="lwc" namespace="lightning"} ::::: ::::::