|
| 1 | +# igxChip Component |
| 2 | + |
| 3 | +The **igxChip** is a compact visual component that displays information in an obround. Chip can be templated, deleted, and selected. Multiple chips can be reordered and visually connected to each other. Chips reside in a container called chips area which is responsible for managing the interactions between the chips. |
| 4 | + |
| 5 | +#### Initializing Chips |
| 6 | + |
| 7 | +The `IgxChipComponent` is the main class for a chip elemenent and the `IgxChipsAreaComponent` is the main class for the chip area. The chip area is used when handling more complex scenarios that require interaction between chips (dragging, selection, navigation and etc.). The `IgxChipComponent` requires an `id` to be defined so that the different chips can be easily distinguished. |
| 8 | + |
| 9 | +Example of using `igxChip` with `igxChipArea`: |
| 10 | + |
| 11 | +```html |
| 12 | +<igx-chips-area> |
| 13 | + <igx-chip *ngFor="let chip of chipList" [id]="chip.id"> |
| 14 | + <span #label [class]="'igx-chip__text'">{{chip.text}}</span> |
| 15 | + </igx-chip> |
| 16 | +</igx-chips-area> |
| 17 | +``` |
| 18 | + |
| 19 | +### Features |
| 20 | + |
| 21 | +#### Selection |
| 22 | + |
| 23 | +Selection is disabled by default, but can be enabled with an option called `selectable`. The selecting is done by clicking on the chip itself or either by focusing the chip by using the `Tab` key and then pressing the `Space` key. An event `onSelection` is fired when the selection state of the `igxChip` changes. If a chip is already selected it can be deselected by pressing the `Space` key again while the chip is focused or by clicking on it. |
| 24 | + |
| 25 | +```html |
| 26 | +<igx-chips-area #chipsArea> |
| 27 | + <igx-chip *ngFor="let chip of chipList" [selectable]="'true'"> |
| 28 | + <span #label [class]="'igx-chip__text'">{{chip.text}}</span> |
| 29 | + </igx-chip> |
| 30 | +</igx-chips-area> |
| 31 | +``` |
| 32 | + |
| 33 | +```ts |
| 34 | +public ngOnInit() { |
| 35 | + chipsArea.forEach((chip) => { |
| 36 | + chip.selectable = true; |
| 37 | + }); |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +#### Removing |
| 42 | + |
| 43 | +The `remove button` is part of the chip as well. You can control the remove button visibility by the `removable` boolean option. An event `onRemove` is fired when the end-user deletes a chip. |
| 44 | + |
| 45 | +```html |
| 46 | +<igx-chips-area #chipsArea> |
| 47 | + <igx-chip *ngFor="let chip of chipList" [id]="chip.id" [removable]="'true'" (onRemove)="chipRemoved($event)"> |
| 48 | + <span #label [class]="'igx-chip__text'">{{chip.text}}</span> |
| 49 | + </igx-chip> |
| 50 | +</igx-chips-area> |
| 51 | +``` |
| 52 | + |
| 53 | +```ts |
| 54 | +public ngOnInit() { |
| 55 | + chipsArea.forEach((chip) => { |
| 56 | + chip.removable = true; |
| 57 | + }); |
| 58 | +} |
| 59 | + |
| 60 | +public chipRemoved(event) { |
| 61 | + this.chipList = this.chipList.filter((item) => { |
| 62 | + return item.id !== event.owner.id; |
| 63 | + }); |
| 64 | + this.cdr.detectChanges(); |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +#### Moving/Dragging |
| 69 | + |
| 70 | +The chip can be dragged by the end-user in order to change it's position. The moving/dragging is disabled by default, but can be enabled with an option called `draggable`. You need to handle the actual moving of the chip in the data source manually. |
| 71 | + |
| 72 | +```html |
| 73 | +<igx-chips-area #chipArea (onReorder)="chipsOrderChanged($event)"> |
| 74 | + <igx-chip *ngFor="let chip of chipList" [draggable]="'true'"> |
| 75 | + <span #label [class]="'igx-chip__text'">{{chip.text}}</span> |
| 76 | + </igx-chip> |
| 77 | +</igx-chips-area> |
| 78 | +``` |
| 79 | + |
| 80 | +```ts |
| 81 | +public ngOnInit() { |
| 82 | + chipArea.forEach((chip) => { |
| 83 | + chip.draggable = true; |
| 84 | + }); |
| 85 | +} |
| 86 | + |
| 87 | +public chipsOrderChanged(event) { |
| 88 | + const newChipList = []; |
| 89 | + for (const chip of event.chipsArray) { |
| 90 | + const chipItem = this.chipList.filter((item) => { |
| 91 | + return item.id === chip.id; |
| 92 | + })[0]; |
| 93 | + newChipList.push(chipItem); |
| 94 | + } |
| 95 | + this.chipList = newChipList; |
| 96 | + event.isValid = true; |
| 97 | +} |
| 98 | + |
| 99 | +``` |
| 100 | + |
| 101 | +#### Chip Templates |
| 102 | + |
| 103 | +The `IgxChipComponent`'s main structure consists of chip content, `remove button`, `prefix`, `suffix` and `connector`. All of those elements are templatable except the `remove button`. |
| 104 | + |
| 105 | +The content of the chip is taken by the content defined inside the chip template except elements that define the `prefix`, `suffix` or `connector` of the chip. You can define any type of content you need. |
| 106 | + |
| 107 | +The `prefix` and `suffix` are also elements inside the actual chip area where they can be templated by your preference. The way they can be specified is by respectively using the `IgxPrefix` and `IxgSuffix` directives. |
| 108 | + |
| 109 | +Example of using an icon for `prefix`, a text for `label` and a custom icon button for `suffix`: |
| 110 | + |
| 111 | +```html |
| 112 | +<igx-chip *ngFor="let chip of chipList" [id]="chip.id"> |
| 113 | + <igx-icon igxPrefix fontSet="material" [name]="'drag_indicator'"></igx-icon> |
| 114 | + <span #label [class]="'igx-chip__text'">{{chip.text}}</span> |
| 115 | + <span igxSuffix *ngIf="removable" igxButton="icon" (click)="onClick()"> |
| 116 | + <igx-icon fontSet="material" [name]="'close'"></igx-icon> |
| 117 | + </span> |
| 118 | +</igx-chip> |
| 119 | +``` |
| 120 | + |
| 121 | +The `connectors` of the `igxChip` are fully templatable and are positioned after each chip. Their purpose is to provide a way to link two chips next to each other with an icon/text or anything you would like to use. The last chip (most right) does not have connector applied. Connectors hide while dragging chips around and show again when interactions with the chips have finished. The connector is defined by using the `IgxConnector` directive. |
| 122 | + |
| 123 | +Example of using prefix connector: |
| 124 | + |
| 125 | +```html |
| 126 | +<igx-chip *ngFor="let chip of chipList" [id]="chip.id"> |
| 127 | + <span #label [class]="'igx-chip__text'">{{chip.text}}</span> |
| 128 | + <span igxConnector> -> </span> |
| 129 | +</igx-chip> |
| 130 | +``` |
| 131 | + |
| 132 | +Example of using suffix connector: |
| 133 | + |
| 134 | +```html |
| 135 | +<igx-chip *ngFor="let chip of chipList" [id]="chip.id"> |
| 136 | + <span #label [class]="'igx-chip__text'">{{chip.text}}</span> |
| 137 | + <span igxSuffixConnector> -> </span> |
| 138 | +</igx-chip> |
| 139 | +``` |
| 140 | + |
| 141 | +#### Keyboard Navigation |
| 142 | + |
| 143 | +The chip can be focused using the `Tab` key or by clicking on them. Chips can be reordered using keyboard navigation: |
| 144 | + |
| 145 | +- Keyboard controls when the chip is focused: |
| 146 | + |
| 147 | + - <kbd>LEFT</kbd> - Focuses the chip on the left |
| 148 | + - <kbd>RIGHT</kbd> - Focuses the chip on the right |
| 149 | + - <kbd>SPACE</kbd> - Toggles chip selection if it is selectable |
| 150 | + - <kbd>DELETE</kbd> - Fires the `onRemove` output so the chip deletion can be handled manually |
| 151 | + - <kbd>SHIFT</kbd> + <kbd>LEFT</kbd> - Moves the focused chip one position to the left |
| 152 | + - <kbd>SHIFT</kbd> + <kbd>RIGHT</kbd> - Moves the focused chip one position to the right |
| 153 | + |
| 154 | +- Keyboard controls when the remove button is focused: |
| 155 | + |
| 156 | + - <kbd>SPACE</kbd> or <kbd>ENTER</kbd> Fires the `onRemove` output so the chip deletion can be handled manually |
| 157 | + |
| 158 | +# API |
| 159 | + |
| 160 | +## IgxChipComponent |
| 161 | + |
| 162 | +### Inputs |
| 163 | +| Name | Type | Description | |
| 164 | +|:----------|:-------------:|:------| |
| 165 | +| `id` | `string` | Unique identifier of the component. | |
| 166 | +| `draggable ` | `boolean` | Defines if the chip can be dragged in order to change it's position. | |
| 167 | +| `removable ` | `boolean` | Defines if the chip should render remove button and throw remove events. | |
| 168 | +| `selectable ` | `boolen` | Defines if the chip can be selected on click or through navigation. | |
| 169 | +| `selected` | `boolen` | Sets if the chip is selected. | |
| 170 | +| `disabled` | `boolean` | Defines if the chip is disabled. | |
| 171 | +| `displayDensity`| `DisplayDensity | string` | Sets the chip theme. Available options are `compact`, `cosy`, `comfortable`. | |
| 172 | +| `color` | `string` | Sets the chip background color. | |
| 173 | + |
| 174 | +### Outputs |
| 175 | +| Name | Return Type | Description | |
| 176 | +|:--:|:---|:---| |
| 177 | +| `onMoveStart` | `any` | Fired when the chip moving(dragging) starts. | |
| 178 | +| `onMoveEnd` | `any` | Fired when the chip moving(dragging) end. | |
| 179 | +| `onRemove ` | `any` | Fired when the chip remove button is clicked. | |
| 180 | +| `onClick ` | `any` | Fired when the chip is clicked instead of dragged. | |
| 181 | +| `onSelection` | `IChipSelectEventArgs` | Fired when the chip is being selected. | |
| 182 | +| `onKeyDown ` | `any` | Fired when the chip keyboard navigation is being used. | |
| 183 | +| `onDragEnter ` | `any` | Fired when another chip has entered the current chip area. | |
| 184 | + |
| 185 | +## IgxChipsAreaComponent |
| 186 | + |
| 187 | +### Inputs |
| 188 | +| Name | Type | Description | |
| 189 | +|:----------|:-------------:|:------| |
| 190 | +| `width` | `number` | Sets the width of the chips area. | |
| 191 | +| `height ` | `number` | Sets the height of the chip area. | |
| 192 | + |
| 193 | +### Outputs |
| 194 | +| Name | Return Type | Description | |
| 195 | +|:--:|:---|:---| |
| 196 | +| `onReorder ` | `any` | Fired when the chip moving(dragging) starts. | |
| 197 | +| `onSelection ` | `any` | Fired when the chip moving(dragging) end. | |
| 198 | +| `onMoveStart ` | `any` | Fired when the chip remove button is clicked. | |
| 199 | +| `onMoveEnd ` | `any` | Fired when the chip is clicked instead of dragged. | |
| 200 | + |
| 201 | +### Properties |
| 202 | +| Name | Return Type | Description | |
| 203 | +|:----------:|:------|:------| |
| 204 | +| `chipsList` | `QueryList<IgxChipComponent>` | Returns the list of chips inside the chip area. | |
0 commit comments