> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/pill-container.md).

# 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.

```html
<!-- 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>
```

```js
// 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.

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

```js
// 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 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 <support@avonni.app> for assistance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avonnicomponents.com/lwc-components/core-components/pill-container.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.