[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url]
[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]
A collection of individual, keyboard accessible, chips. Useful for displaying choice collections.
NOTE: This component does not support a `FormControl`; it is a simple collection display.
## Table of Contents
- [Installation](#installation)
- [CSS imports](#css-imports)
- [CSS resources](#css-resources)
- [Usage](#usage)
- [Using the DOM as value](#using-the-dom-as-value)
- [Orientation](#orientation)
- [Removable](#removable)
- [Selectable](#selectable)
- [Badge](#badge)
- [Background color](#background-color)
- [Events](#events)
- [Collection events](#collection-events)
- [Chip events](#chip-events)
- [Test Helpers](#test-helpers)
## Installation
Using `ng add` command can help getting all the dependencies installed:
```bash
ng add @terminus/ui-chip
```
### CSS imports
In your top-level stylesheet, add these imports:
```css
@import '~@terminus/design-tokens/css/library-design-tokens.css';
@import '~@terminus/ui-styles/terminus-ui.css';
```
### CSS resources
Load the needed font families by adding this link to the `` of your application:
```css
```
## Usage
Create a collection of chips:
```typescript
myChips = ['one', 'two', 'three'];
```
```html
{{ chip }}
```
### Using the DOM as value
For string based collections, the value input can be disregarded as the value will be pulled directly from the DOM.
```html
{{ chip }}
```
### Orientation
A collection of chips can be displayed in a row (`horizontal`) or a column (`vertical`) via the `orientation` input. By
default it displays as a row.
```html
{{ chip }}
```
### Removable
By default, chips are 'removable'. Since this component does not directly manage the data, when a user attempts to
remove a chip, an event is emitted. The consumer is responsible to use that event to remove the item from the
collection. (See [Events](#events))
```html
{{ chip }}
```
```typescript
myChips = ['apple', 'banana'];
removeChip(removeEvent: TsChipEvent): void {
const index = this.myChips.indexOf(removeEvent.chip.value);
if (index < 0) {
return;
}
this.myChips.splice(index, 1);
}
```
The ability to remove a chip can be disabled per chip or as a collection:
```html
{{ chip }}
{{ chip }}
```
### Selectable
Chips can be selected and will visually show that selection.
The ability to select chips can be disabled per chip or as a collection:
```html
{{ chip }}
{{ chip }}
```
### Badge
A chip can be used as a badge by placing the `tsChipBadge` directive on a standalone chip:
```html
My badge!
```
This will disable the ability to remove, select or focus the chip.
#### Background color
You can change the badge background color by overriding this CSS custom property:
```css
:root {
--ts-chip-badge-backgroundColor: #bada55;
}
```
### Events
Since this component does not directly manage the data, we rely on emitting events to alert the consumer for any user
interaction.
#### Collection events
| Event | Description | Payload |
|:-------------------|:-----------------------------------------------|:-------------------------|
| `collectionChange` | Fired when any chips are added or removed | `TsChipCollectionChange` |
| `removed` | Fired when a chip is removed | `TsChipEvent` |
| `tabUpdateFocus` | Fired when the user tabs out of the collection | `void` |
#### Chip events
| Event | Description | Payload |
|:------------------|:--------------------------------------------|:------------------------|
| `clicked` | Fired when the chip is clicked | `TsChipClickEvent` |
| `destroyed` | Fired when the chip is destroyed | `TsChipEvent` |
| `blurred` | Fired when focus leaves the chip | `void` |
| `remove` | Fired when the chip should be removed | `TsChipEvent` |
| `selectionChange` | Fired when the chip selection state changes | `TsChipSelectionChange` |
## Test Helpers
Some helpers are exposed to assist with testing. These are imported from `@terminus/ui-chip/testing`;
[[source]][test-helpers-src]
| Function |
|-------------------------------------------|
| `getAllChipCollectionDebugElements` |
| `getAllChipCollectionInstances` |
| `getChipCollectionInstance` |
| `getChipCollectionElement` |
| `getAllChipInstances` |
| `getChipInstance` |
| `getAllChipDebugElements` |
| `getChipDebugElement` |
| `getChipCollectionDebugElement` |
| `getChipElement` |
[test-helpers-src]: testing/src/test-helpers.ts
[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE
[license-image]: http://img.shields.io/badge/license-MIT-blue.svg
[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss
[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg
[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-chip.svg
[npm-package]: https://www.npmjs.com/package/@terminus/ui-chip
[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg
[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22
[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-chip/bundles/terminus-ui-chip.umd.min.js?compression=gzip
[raw-distribution-js]: https://unpkg.com/@terminus/ui-chip/bundles/terminus-ui-chip.umd.js
---
_Source: https://npm.io/package/@terminus/ui-chip · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._