@terminus/ui-chip NPM

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.

Installation

Using ng add command can help getting all the dependencies installed:

ng add @terminus/ui-chip

CSS imports

In your top-level stylesheet, add these imports:

@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 <head> of your application:

<link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400&display=swap" rel="stylesheet">

Usage

Create a collection of chips:

myChips = ['one', 'two', 'three'];

<ts-chip-collection>
  <ts-chip
    *ngFor="let chip of myChips;"
    [value]="chip"
  >{{ chip }}</ts-chip>
</ts-chip-collection>

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.

<ts-chip-collection>
  <ts-chip *ngFor="let chip of ['foo', 'bar', 'baz']">
    {{ chip }}
  </ts-chip>
</ts-chip-collection>

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.

<ts-chip-collection>
  <ts-chip
    *ngFor="let chip of chips"
    orientation="vertical"
  >{{ chip }}</ts-chip>
</ts-chip-collection>

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)

<ts-chip-collection>
  <ts-chip
    *ngFor="let chip of myChips"
    (remove)="removeChip($event)"
  >{{ chip }}</ts-chip>
</ts-chip-collection>

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:

<!-- Disable the chip directly -->
<ts-chip-collection>
  <ts-chip
    *ngFor="let chip of chips"
    [isRemovable]="false"
  >{{ chip }}</ts-chip>
</ts-chip-collection>

<!-- Disable for the entire collection -->
<ts-chip-collection [isRemovable]="false">
  <ts-chip *ngFor="let chip of chips">
    {{ chip }}
  </ts-chip>
</ts-chip-collection>

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:

<!-- Disable on the chip directly -->
<ts-chip-collection>
  <ts-chip
    *ngFor="let chip of chips"
    [isSelectable]="false"
  >{{ chip }}</ts-chip>
</ts-chip-collection>

<!-- Disable for the entire collection -->
<ts-chip-collection [isSelectable]="false">
  <ts-chip *ngFor="let chip of chips">
    {{ chip }}
  </ts-chip>
</ts-chip-collection>

Badge

A chip can be used as a badge by placing the tsChipBadge directive on a standalone chip:

<ts-chip tsChipBadge>My badge!</ts-chip>

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:

: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]

Function
`getAllChipCollectionDebugElements`
`getAllChipCollectionInstances`
`getChipCollectionInstance`
`getChipCollectionElement`
`getAllChipInstances`
`getChipInstance`
`getAllChipDebugElements`
`getChipDebugElement`
`getChipCollectionDebugElement`
`getChipElement`