> 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/chip-container.md).

# Chip Container

`avonni-chip-container`

Displays a collection of chips, with support for wrapping, single-line layouts and reordering.

## Overview

**Chip Container** is a Lightning Web Component that displays a list of chips— compact labels with optional icons, avatars, and styling variants—that can be collapsed, expanded, or reordered.

Use it in your own Lightning Web Components to show tags, filters, statuses, or selected items as a group. You control the items, whether the list collapses, whether chips can be reordered by drag-and-drop or keyboard, and the assistive text—all through the component's attributes.

### Use Cases

* **Tag lists:** Display a record's labels or categories as chips.
* **Selected filters:** Show active filters that users can review at a glance.
* **Status groups:** Surface multiple statuses with color-coded variants.
* **Reorderable lists:** Let users drag or keyboard-sort chips into priority order.
* **Collapsible groups:** Hide overflow chips behind a "show more" button.

***

## Chip Item Properties

| Property                            | Use Case                                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------------------------ |
| `label` / `name`                    | Visible text and unique identifier for the chip.                                           |
| `variant`                           | Color style: `base`, `brand`, `warning`, `success`, `error`, `info`, `inverse`, `offline`. |
| `outline`                           | Renders the chip with an outline style.                                                    |
| `prefixIconName` / `suffixIconName` | SLDS icon shown before or after the label.                                                 |
| `avatar`                            | Avatar object (e.g. initials, fallback icon) shown in the chip.                            |

***

## Use Case Examples

### Example 1: Status chips with icons and avatars

**Scenario:** Show a set of color-coded status chips, some with leading or trailing icons and one with an avatar.

```html
<!-- statusChips.html -->
<template>
    <avonni-chip-container items={items}></avonni-chip-container>
</template>
```

```js
// statusChips.js
import { LightningElement } from 'lwc';

export default class StatusChips extends LightningElement {
    items = [
        { label: 'New', name: 'new', variant: 'brand', prefixIconName: 'utility:add' },
        { label: 'In Progress', name: 'in-progress', variant: 'warning', prefixIconName: 'utility:clock' },
        { label: 'Completed', name: 'completed', variant: 'success', suffixIconName: 'utility:check' },
        {
            label: 'Jane Doe',
            name: 'jane-doe',
            variant: 'base',
            avatar: { fallbackIconName: 'standard:user', initials: 'JD', variant: 'circle', position: 'left' }
        }
    ];
}
```

**Result:** A row of styled chips—each colored by variant, with icons or an avatar reinforcing its meaning.

### Example 2: Sortable, collapsible chips

**Scenario:** Let users reorder chips with drag-and-drop or the keyboard, and collapse the overflow.

```html
<!-- sortableChips.html -->
<template>
    <avonni-chip-container
        items={items}
        alternative-text="Sortable chips. Press spacebar to grab or drop an item. Press right and left arrow keys to change position. Press escape to cancel."
        show-more-button-alternative-text="Show more chips"
        is-collapsible
        is-expanded
        sortable
        onreorder={handleReorder}
        onexpand={handleExpand}
    ></avonni-chip-container>
</template>
```

```js
// sortableChips.js
import { LightningElement } from 'lwc';

export default class SortableChips extends LightningElement {
    items = [
        { label: 'New', name: 'new', variant: 'brand' },
        { label: 'In Progress', name: 'in-progress', variant: 'warning' },
        { label: 'Completed', name: 'completed', variant: 'success' }
    ];

    handleReorder(event) {
        const newOrder = event.detail.items.map((item) => item.name);
    }

    handleExpand() {
        // collapsed chips were expanded
    }
}
```

**Result:** A collapsible, reorderable chip list; reordering fires `reorder` with the items in their new order.

***

## Specifications

### Attributes

| Name                                | Description                                                                                                                                                                                                                                                                  | Type                       | Default       | Required |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------- | -------- |
| `alternative-text`                  | Alternative text used to describe the chip container. If the chip container is sortable, it should describe its behavior, for example: "Sortable chips. 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 chip list can be collapsed. Use is-collapsible with the is-expanded attribute to expand and collapse the list of chips.                                                                                                                                      | Boolean                    | `false`       |          |
| `is-expanded`                       | If present and is-collapsible too, the list of chips is expanded. This attribute is ignored when is-collapsible is false, and the list of chips is expanded even if is-expanded is false or not set.                                                                         | Boolean                    | `false`       |          |
| `items`                             | Array of item objects to display as chips in the container.                                                                                                                                                                                                                  | AvonniChipContainerItem\[] | —             |          |
| `show-more-button-alternative-text` | The alternative text used to describe the show more button.                                                                                                                                                                                                                  | String                     | `"Show more"` |          |
| `single-line`                       | If present, the chips are limited to one line. This attribute overrides the is-collapsible and is-expanded attributes.                                                                                                                                                       | Boolean                    | `false`       |          |
| `sortable`                          | If present, the chips 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 chip list. |               |               |                      |

### Custom Events

#### `blur`

The event fired when the chip 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 chips 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 chip 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 chips.

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-chip-container-color-background`     | color     | `transparent` |
| `--avonni-chip-container-color-border`         | color     | `#747474`     |
| `--avonni-chip-container-radius-border`        | dimension | `0.25rem`     |
| `--avonni-chip-container-spacing-block-end`    | dimension | `0.125rem`    |
| `--avonni-chip-container-spacing-block-start`  | dimension | `0.125rem`    |
| `--avonni-chip-container-spacing-inline-end`   | dimension | `0.125rem`    |
| `--avonni-chip-container-spacing-inline-start` | dimension | `0.125rem`    |
| `--avonni-chip-alt-inverse-color-background`   | color     | `#032d60`     |
| `--avonni-chip-alt-inverse-color-border`       | color     | `transparent` |
| `--avonni-chip-alt-inverse-text-color`         | color     | `#ffffff`     |
| `--avonni-chip-alt-inverse-outline-color`      | color     | `#032d60`     |
| `--avonni-chip-base-color-background`          | color     | `#032d60`     |
| `--avonni-chip-base-color-border`              | color     | `transparent` |
| `--avonni-chip-base-text-color`                | color     | `#080707`     |
| `--avonni-chip-base-outline-color`             | color     | `#032d60`     |
| `--avonni-chip-brand-color-background`         | color     | `#0070d1`     |
| `--avonni-chip-brand-color-border`             | color     | `transparent` |
| `--avonni-chip-brand-text-color`               | color     | `#ffffff`     |
| `--avonni-chip-brand-outline-color`            | color     | `#0070d1`     |
| `--avonni-chip-error-color-background`         | color     | `#ba0517`     |
| `--avonni-chip-error-color-border`             | color     | `transparent` |
| `--avonni-chip-error-text-color`               | color     | `#ffffff`     |
| `--avonni-chip-error-outline-color`            | color     | `#ba0517`     |
| `--avonni-chip-info-color-background`          | color     | `#706e6b`     |
| `--avonni-chip-info-color-border`              | color     | `transparent` |
| `--avonni-chip-info-text-color`                | color     | `#ffffff`     |
| `--avonni-chip-info-outline-color`             | color     | `#706e6b`     |
| `--avonni-chip-inverse-color-background`       | color     | `#001639`     |
| `--avonni-chip-inverse-color-border`           | color     | `transparent` |
| `--avonni-chip-inverse-text-color`             | color     | `#ffffff`     |
| `--avonni-chip-inverse-outline-color`          | color     | `#001639`     |
| `--avonni-chip-offline-color-background`       | color     | `#444444`     |
| `--avonni-chip-offline-color-border`           | color     | `transparent` |
| `--avonni-chip-offline-text-color`             | color     | `#ffffff`     |
| `--avonni-chip-offline-outline-color`          | color     | `#444444`     |
| `--avonni-chip-success-color-background`       | color     | `#2e844a`     |
| `--avonni-chip-success-color-border`           | color     | `transparent` |
| `--avonni-chip-success-text-color`             | color     | `#ffffff`     |
| `--avonni-chip-success-outline-color`          | color     | `#2e844a`     |
| `--avonni-chip-warning-color-background`       | color     | `#dd7a01`     |
| `--avonni-chip-warning-color-border`           | color     | `transparent` |
| `--avonni-chip-warning-text-color`             | color     | `#080707`     |
| `--avonni-chip-warning-outline-color`          | color     | `#dd7a01`     |
| `--avonni-chip-label-font-size`                | font      | `0.75rem`     |
| `--avonni-chip-cursor`                         | string    | `default`     |
| `--avonni-chip-radius-border`                  | dimension | `15rem`       |
| `--avonni-chip-sizing-border`                  | sizing    | `1px`         |
| `--avonni-chip-styling-border`                 | styling   | `solid`       |
| `--avonni-chip-line-height`                    | dimension | `normal`      |
| `--avonni-chip-spacing-block-start`            | dimension | `0.25rem`     |
| `--avonni-chip-spacing-block-end`              | dimension | `0.25rem`     |
| `--avonni-chip-spacing-inline-start`           | dimension | `0.5rem`      |
| `--avonni-chip-spacing-inline-end`             | dimension | `0.5rem`      |
| `--avonni-chip-container-sizing-border`        | sizing    | `1px`         |
| `--avonni-chip-container-styling-border`       | string    | `solid`       |

## Key Considerations

* **Unique names:** Give each item a `name` so `reorder` payloads identify chips.
* **Sorting accessibility:** Describe the keyboard sort controls in `alternative-text` whenever `sortable` is set.
* **Collapse vs. single line:** `single-line` overrides the collapsible behavior—choose one approach per container.
* **Variants:** Match chip `variant` to meaning so color reinforces status.
* **Best Practice:** When `sortable` is set, use `alternative-text` to explain the keyboard controls (spacebar to grab/drop, arrow keys to move, escape to cancel).

***

## Troubleshooting Common Issues

* **Chips not collapsing:** Confirm `is-collapsible` is set and `single-line` is not (it overrides collapsing).
* **Reorder not working:** Ensure `sortable` is set; reordering then fires the `reorder` event with the new order.
* **Expand button not appearing:** The list must overflow and `is-collapsible` must be set for the "show more" button to render.
* **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/chip-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.