# Chip set

Bootstrap Chip set component for CoreUI — group chips into an accessible, keyboard-navigable container with single or multiple selection.

## Overview

The CoreUI **Bootstrap Chip set component** groups multiple [chips](/components/chip/) into a single container that manages roving focus, keyboard navigation, and selection. While an individual chip handles its own state (selection, removal), the chip set is responsible for everything that spans the whole group:

- Arrow-key navigation between chips, with <kbd>Home</kbd>/<kbd>End</kbd> jumping to the edges.
- Moving focus to a neighboring chip after one is removed.
- Single or multiple selection through the `selectionMode` option.
- A flexible, wrapping layout with a configurable gap.

A chip set instantiates the child `.chip` elements for you, so you don't need to initialize each chip separately.

## Basic chip set

Wrap your chips in `.chip-set` and enable the plugin with `data-coreui-chip-set`.

```html
<div class="chip-set" data-coreui-chip-set>
  <span class="chip">Apple</span>
  <span class="chip">Banana</span>
  <span class="chip">Cherry</span>
  <span class="chip">Date</span>
</div>
```

## Selectable chips

Set `data-coreui-selectable="true"` to make every chip in the set selectable. With the default `selectionMode` of `multiple`, any number of chips can be active at once — useful for filters.

```html
<div class="chip-set" data-coreui-chip-set data-coreui-selectable="true">
  <span class="chip">Design</span>
  <span class="chip active">Development</span>
  <span class="chip">Marketing</span>
  <span class="chip active">Sales</span>
</div>
```

### Single selection

Use `data-coreui-selection-mode="single"` to allow only one selected chip at a time — selecting a chip deselects its siblings. This is useful for choice chips.

```html
<div class="chip-set" data-coreui-chip-set data-coreui-selectable="true" data-coreui-selection-mode="single">
  <span class="chip active">Small</span>
  <span class="chip">Medium</span>
  <span class="chip">Large</span>
</div>
```

## Filter chips

Add `data-coreui-filter="true"` to turn the chips into filter chips. A check icon is shown on each selected chip and removed when it is deselected. `filter` implies `selectable`, so you don't need to set both.

```html
<div class="chip-set" data-coreui-chip-set data-coreui-filter="true">
  <span class="chip">Design</span>
  <span class="chip active">Development</span>
  <span class="chip">Marketing</span>
  <span class="chip active">Sales</span>
</div>
```

Customize the check with the `selectedIcon` option (or `data-coreui-selected-icon`), the same way you customize the remove icon.

## Removable chips

Set `data-coreui-removable="true"` to add a remove button to every chip. When a chip is removed, focus moves to a neighboring chip.

```html
<div class="chip-set" data-coreui-chip-set data-coreui-removable="true">
  <span class="chip">Filter one</span>
  <span class="chip">Filter two</span>
  <span class="chip disabled">Filter three</span>
</div>
```

## JavaScript plugin

<div class="docs-callout docs-callout-warning">
  <p>
    <strong>Heads up!</strong> In our documentation, all examples show <a href="https://coreui.io/bootstrap/docs/getting-started/introduction/#quick-start">standard CoreUI implementation</a>. If you are using a <a href="https://coreui.io/bootstrap/docs/getting-started/introduction/#bootstrap-replacement">Bootstrap-compatible</a> version of CoreUI, remember to use the following changes:
    <ul>
      <li>In the constructor, please use <strong>bootstrap</strong> instead of <strong>coreui</strong>. For example, <code>new bootstrap.Alert(...)</code> instead of <code>new coreui.Alert(...)</code></li>
      <li>In events, please use <strong>bs</strong> instead of <strong>coreui</strong>, for example <code>close.bs.alert</code> instead of <code>close.coreui.alert</code></li>
      <li>In data attributes, please use <strong>bs</strong> instead of <strong>coreui</strong>. For example, <code>data-bs-toggle="..."</code> instead of <code>data-coreui-toggle="..."</code></li>
    </ul>
  </p>
</div>

### Data attributes

Add `data-coreui-chip-set` to enable the plugin and configure behavior with `data-coreui-*` options. The options are forwarded to every chip in the set.

```html
<div class="chip-set" data-coreui-chip-set data-coreui-selectable="true" data-coreui-selection-mode="single">
  <span class="chip">One</span>
  <span class="chip">Two</span>
</div>
```

### JavaScript

```js
const chipSet = document.querySelector('#myChipSet')
coreui.ChipSet.getOrCreateInstance(chipSet, {
  selectable: true,
  selectionMode: 'single'
})
```

### Options

<p>Options can be passed using data attributes or JavaScript. To do this, append an option name to <code>data-coreui-</code>, such as <code>data-coreui-animation=&quot;{value}&quot;</code>. Remember to convert the case of the option name from &ldquo;<em>camelCase</em>&rdquo; to &ldquo;<em>kebab-case</em>&rdquo; when using data attributes. For instance, you should write <code>data-coreui-custom-class=&quot;beautifier&quot;</code> rather than <code>data-coreui-customClass=&quot;beautifier&quot;</code>.</p>
<p>Starting with CoreUI 4.2.0, all components support an <strong>experimental</strong> reserved data attribute named <code>data-coreui-config</code>, which can contain simple component configurations as a JSON string. If an element has attributes <code>data-coreui-config='{&quot;delay&quot;:50, &quot;title&quot;:689}'</code> and <code>data-coreui-title=&quot;Custom Title&quot;</code>, then the final value for <code>title</code> will be <code>Custom Title</code>, as the standard data attributes will take precedence over values specified in <code>data-coreui-config</code>. Moreover, existing data attributes can also hold JSON values like <code>data-coreui-delay='{&quot;show&quot;:50, &quot;hide&quot;:250}'</code>.</p>



| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `ariaRemoveLabel` | string | `'Remove'` | Accessible label applied to each chip's remove button. |
| `chipClassName` | string, function, null | `null` | CSS class(es) added to chips created through `add`. A function receives the chip value and returns the class string. |
| `disabled` | boolean | `false` | Disables interactions and focus for the chips in the set. |
| `filter` | boolean | `false` | Turns the chips into filter chips — a check icon is shown on the selected ones. Implies `selectable`. |
| `maxChips` | number, null | `null` | Maximum number of chips allowed. `null` means no limit. |
| `removable` | boolean | `false` | Adds a remove button to each chip. |
| `removeIcon` | string | SVG | HTML string used as the remove icon. |
| `selectable` | boolean | `false` | Enables selection and keyboard selection on the chips. |
| `selectedIcon` | string | SVG | HTML string used as the check icon on selected filter chips. |
| `selectionMode` | string | `'multiple'` | Selection behavior: `'multiple'` allows several active chips, `'single'` keeps at most one. |
| `unique` | boolean | `false` | Prevents adding a chip whose value already exists in the set. |


### Methods


| Method | Description |
| --- | --- |
| `add` | Adds a chip to the set. Accepts an existing `.chip` element or a label string (a chip element is created for you). Honors `unique` and `maxChips`. Returns the chip element (or `null` if rejected). |
| `remove` | Removes a chip from the set. Accepts a chip element or its value string. |
| `removeSelected` | Removes every selected chip from the set. |
| `clear` | Removes every chip from the set. |
| `getValues` | Returns the array of chip values. |
| `getSelected` | Returns an array of the selected (`.active`) chip elements. |
| `getSelectedValues` | Returns the values of the selected chips. |
| `selectChip` | Selects a specific chip element belonging to the set. |
| `selectAll` | Selects every selectable chip in the set. |
| `deselectAll` | Deselects every selected chip in the set. |
| `clearSelection` | Deselects all chips and emits a selection change. |
| `dispose` | Destroys a chip set instance. (Removes stored data on the DOM element) |
| `getInstance` | Static method to get the chip set instance: `coreui.ChipSet.getInstance(element)`. |
| `getOrCreateInstance` | Static method to get or create a chip set instance: `coreui.ChipSet.getOrCreateInstance(element)`. |


### Events

Chip set events are fired from the chip set element. Individual `*.coreui.chip` events still fire from each chip and bubble up.


| Event type | Description |
| --- | --- |
| `add.coreui.chip-set` | Fires immediately before a chip is added through `add`. Cancelable. Carries the `value`. |
| `remove.coreui.chip-set` | Fires immediately before a chip is removed through `remove`. Cancelable. Carries the `value` and `chip` element. |
| `change.coreui.chip-set` | Fired when the set's membership changes (a chip is added or removed). Carries the current `values` array. |
| `select.coreui.chip-set` | Fired when the selection changes. Carries the `selected` array of chip values. |


```js
const myChipSet = document.getElementById('myChipSet')
myChipSet.addEventListener('change.coreui.chip-set', event => {
  // event.values is the array of chip values
})
```

## Keyboard behavior

When a chip inside a chip set is focused:


| Key | Action |
| --- | --- |
| `Enter` / `Space` | Toggle selection of the focused chip (when `selectable` is enabled) |
| `Backspace` / `Delete` | Remove the focused chip (when `removable` is enabled) |
| `←` | Move focus to the previous chip |
| `→` | Move focus to the next chip |
| `Home` | Move focus to the first chip |
| `End` | Move focus to the last chip |


Disabled chips (`.chip.disabled`) are skipped while navigating.

## Accessibility

- The chip set manages roving focus, so the arrow keys move focus between chips rather than relying on the browser's default tab order.
- Add a descriptive `aria-label` to the chip set element when the group has a meaningful role (e.g., "Applied filters").
- Selection state is reflected on each chip via `aria-selected`; see the [Chip](/components/chip/) accessibility notes.

## Customizing

### CSS variables

```scss
--cui-chip-set-gap: #{$chip-set-gap};
```

### SASS variables

```scss
$chip-set-gap: .25rem;

```