Pill Container

avonni-pill-container

Displays a collection of pills representing items or selections, with support for actions and overflow.

Overview

Pill Container is a Lightning Web Component that displays a collection of items as pills, with optional avatars, per-pill actions, collapsing, and drag-and-drop reordering.

Use it in your own Lightning Web Components to show selected values, tags, or related records as removable, reorderable chips. You control the items, the actions on each pill, whether the list collapses or stays on a single line, and whether pills can be sorted—all through the component's attributes.

Use Cases

• Selected filters: Show the user's active filter selections as pills.
• Tags and labels: Display a record's tags with remove actions.
• Related records: List linked records as pills with avatars.
• Reorderable lists: Let users drag or keyboard-sort pills into a preferred order.
• Compact displays: Collapse a long list to a single line with a "+N more" button.

---

Use Case Examples

Example 1: Collapsible, sortable pills with actions

Scenario: Show selected destinations as reorderable pills, each with edit and remove actions, collapsing to a single line when there are many.

<!-- destinations.html -->
<template>
    <avonni-pill-container
        actions={actions}
        alternative-text="Selected destinations. Press spacebar to grab or drop a pill. Press the arrow keys to change position. Press escape to cancel."
        is-collapsible
        is-expanded
        items={items}
        show-more-button-label="more"
        sortable
        onactionclick={handleActionClick}
        onitemclick={handleItemClick}
        onreorder={handleReorder}
    ></avonni-pill-container>
</template>

// destinations.js
import { LightningElement } from 'lwc';

export default class Destinations extends LightningElement {
    items = [
        { label: 'Mountain Lake', name: 'mountain-lake' },
        { label: 'Forest Trail', name: 'forest-trail' }
    ];

    actions = [
        { label: 'Edit', name: 'edit', iconName: 'utility:edit' },
        { label: 'Remove', name: 'remove', iconName: 'utility:delete' }
    ];

    handleActionClick(event) {
        const { name, targetName } = event.detail; // action + item
    }

    handleItemClick(event) {
        const itemName = event.detail.name;
    }

    handleReorder(event) {
        this.items = event.detail.items; // new order
    }
}

Result: A collapsible list of sortable destination pills, each with edit and remove actions; clicking actions and reordering fire the matching events.

Example 2: Simple tag list

Scenario: Display a record's tags as plain pills with no actions.

<!-- tagList.html -->
<template>
    <avonni-pill-container
        items={tags}
        alternative-text="Record tags"
    ></avonni-pill-container>
</template>

// tagList.js
import { LightningElement } from 'lwc';

export default class TagList extends LightningElement {
    tags = [
        { label: 'Priority', name: 'priority' },
        { label: 'Follow up', name: 'follow-up' }
    ];
}

Result: A wrapping row of read-only tag pills.

---

Specifications

Attributes

Name	Description	Type	Default	Required
actions	Array of actions to display to the right of each pill.	AvonniPillContainerActions[]	—
alternative-text	Alternative text used to describe the pill container. If the pill container is sortable, it should describe its behavior, for example: "Sortable pills. Press spacebar to grab or drop an item. Press right and left arrow keys to change position. Press escape to cancel."	String	—
is-collapsible	If present, the pill list can be collapsed. Use is-collapsible with the is-expanded attribute to expand and collapse the list of pills.	Boolean	false
is-expanded	If present and is-collapsible too, the list of pills is expanded. This attribute is ignored when is-collapsible is false, and the list of pills is expanded even if is-expanded is false or not set.	Boolean	false
items	Array of item objects to display as pills in the container.	AvonniPillContainerItem[]	—
show-more-button-label	Label of the show more button displayed after the number of hidden items. E.g. "+2 more"	String	"more"
single-line	If present, the pills are limited to one line. This attribute overrides the is-collapsible and is-expanded attributes.	Boolean	false
sortable	If present, the pills can be reordered by dragging and dropping, or using the spacebar key.	Boolean	false

Methods

Name	Description	Argument Name	Argument Type	Argument Description
focus	Set the focus on the pill list.

Custom Events

actionclick

The event fired when the user clicks on an item's action.

The actionclick event returns the following parameters.

Parameter	Type	Description
name	string	Action name.
targetName	string	Name of the item to which the action belongs.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

blur

The event fired when the pill container loses focus.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

expand

The event fired when the pills are collapsed, and the expand button is clicked.

The expand event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the pill container gains focus.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

itemclick

The event fired when a user clicks on an item.

The itemclick event returns the following parameters.

Parameter	Type	Description
name	string	Name of the item clicked.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

reorder

The event fired when a user reorders the pills.

The reorder event returns the following parameters.

Parameter	Type	Description
items	object[]	Items in their new order.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

actionclick

The event fired when a user clicks on an action.

The actionclick event returns the following parameters.

Parameter	Type	Description
index	number	Index of the item clicked.
targetName	string	Name of the item the action belongs to.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

blur

The event fired when the pill container loses focus.

The blur event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

expand

The event fired when the pills are collapsed, and the expand button is clicked.

The expand event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

focus

The event fired when the pill container gains focus.

The focus event doesn't return any parameters.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

reorder

The event fired when a user reorders the pills.

The reorder event returns the following parameters.

Parameter	Type	Description
items	object[]	Items in their new order.

The event properties are as follows.

Property	Value	Description
bubbles	false	This event does not bubble.
cancelable	false	This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed	false	This event does not propagate outside of the component in which it was dispatched.

Styling Hooks

CSS Variable	Type	Default
--avonni-pill-action-color-background	color	--avonni-pill-color-background
--avonni-pill-action-color-border	color	--avonni-pill-color-border
--avonni-pill-action-text-color	color	#0b5cab
--avonni-pill-action-text-color-hover	color	#014486
--avonni-pill-color-background	color	#ffffff
--avonni-pill-color-background-hover	color	#f3f3f3
--avonni-pill-color-border	color	#747474
--avonni-pill-color-border-hover	color	#747474
--avonni-pill-color-border-focus	color	#1b96ff
--avonni-pill-container-color-background	color	#ffffff
--avonni-pill-container-color-border	color	#747474
--avonni-pill-container-dropdown-sizing-max-height	dimension	17.5rem
--avonni-pill-container-dropdown-sizing-width	dimension	13rem
--avonni-pill-container-radius-border	dimension	0.25rem
--avonni-pill-container-spacing-block-end	dimension	0.125rem
--avonni-pill-container-spacing-block-start	dimension	0.125rem
--avonni-pill-container-spacing-inline-end	dimension	0.125rem
--avonni-pill-container-spacing-inline-start	dimension	0.125rem
--avonni-pill-line-height	number	1.5
--avonni-pill-radius-border	dimension	0.25rem
--avonni-pill-shadow	string	—
--avonni-pill-shadow-focus	string	0 0 3px #0176d3
--avonni-pill-sizing-border	dimension	1px
--avonni-pill-styling-border	styling	solid
--avonni-pill-spacing-block-end	dimension	0.125rem
--avonni-pill-spacing-block-start	dimension	0.125rem
--avonni-pill-spacing-inline-end	dimension	0.125rem
--avonni-pill-spacing-inline-start	dimension	0.125rem
--avonni-pill-text-color	color	#181818
--avonni-pill-text-color-hover	color	#181818

Key Considerations

• Item shape: Each item supports label, name, and an optional avatar object for an icon or initials.
• Collapsing vs. single line: single-line forces one line and overrides is-collapsible/is-expanded.
• Sorting access: When sortable, both drag-and-drop and keyboard (spacebar/arrow keys) reordering are supported.
• Action target: actionclick reports both the action name and the targetName of the pill it belongs to.
• Best Practice: When sortable is set, write alternative-text that explains the keyboard controls (grab/drop with spacebar, move with arrow keys) so the container is accessible.

---

Troubleshooting Common Issues

• Pills not showing: Confirm items is a non-empty array and each item has a label.
• Reorder not working: Set the sortable attribute; without it, pills are fixed in order.
• Actions missing: Provide an actions array; each action needs a name (and usually an iconName).
• If issues persist: Contact our support team at [email protected] for assistance.