@terminus/ui-chip

v4.0.0

Published

3 years ago

<h1>Chip & Chip Collection</h1>

Downloads

0High
0Medium
0Low

bmalinconico-terminus

atlwendy

terminus_devops

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 |