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, inverse, alt-inverse, success, info, warning, error, 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.

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

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

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

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

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 [email protected] for assistance.