# Tag autocomplete

- Entry point: `@koobiq/components/tags`
- NgModule: `KbqTagsModule`
- API: https://koobiq.io/api/tags.md
- Page: https://koobiq.io/en/components/tag-autocomplete/overview

## Overview

Tags Autocomplete is used to select one or multiple values from a list and to input custom values.

When focusing on the field, the dictionary menu opens. Autocomplete changes as you type. Selecting an option from the list adds a tag, clears the text in the field, and closes the menu.

[**Example: Tag autocomplete overview** (`tag-autocomplete-overview`)](https://koobiq.io/examples/tag-autocomplete-overview.md)

The menu belongs to [autocomplete](https://koobiq.io/en/components/autocomplete.md) — its width is configured there, through the `panelWidth` and `panelMinWidth` attributes of `<kbq-autocomplete>`, and is measured against the whole field rather than the input.

### Menu next to the caret

Suggestions can be shown next to the text caret. Set `kbqAutocompleteRelativeToCaret` on the input field to enable this.

[**Example: Tag autocomplete relative to caret** (`tag-autocomplete-relative-to-caret`)](https://koobiq.io/examples/tag-autocomplete-relative-to-caret.md)

### Search

Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the [Smart search guide](https://koobiq.io/en/other/search-smart.md).

[**Example: Tag autocomplete search** (`tag-autocomplete-search`)](https://koobiq.io/examples/tag-autocomplete-search.md)

### Adding to dictionary

The option to create a new tag is placed first in the autocomplete menu. It creates a new token from the entered text if it doesn't exist in the dictionary.

Adding a tag also works with the `Tab` key.

Creating a duplicate of a selected tag is not allowed: the system will show the message `Nothing found`.

[**Example: Tag autocomplete option operations** (`tag-autocomplete-option-operations`)](https://koobiq.io/examples/tag-autocomplete-option-operations.md)

### Tag removal

Tag removal order:

- If there are selected tags, all of them will be removed.
- If there are no selected tags, the focused tag will be removed.

Tags can be removed in several ways:

- Click on the remove icon (`kbqTagRemove` directive) inside the tag.
- Press `Delete` or `Backspace` key.
- Click on the reset control, which removes every tag except the disabled ones.
- Programmatic removal through the component [API](https://koobiq.io/api/tags.md).

The removal option is configured using the `removable` attribute (enabled by default). A disabled tag does not show its remove icon, and a list with `removable="false"` has no reset control either.

[**Example: Tag autocomplete removable** (`tag-autocomplete-removable`)](https://koobiq.io/examples/tag-autocomplete-removable.md)

The reset control needs no handler of its own — it removes the tags through the same `removed` output as the remove icon inside a tag. Which tags it removes is set by the `clearPredicate` attribute: `[clearPredicate]="clearEverything"` and `clearEverything = () => true` clear the disabled ones too.

[**Example: Tag autocomplete cleaner with disabled tags** (`tag-autocomplete-cleaner-with-disabled`)](https://koobiq.io/examples/tag-autocomplete-cleaner-with-disabled.md)

### Tag selection

Tags can be selected in several ways:

- Click on a tag while holding `Ctrl`.
- Click on a tag while holding `Shift` to change the selection range from the anchor tag to the clicked tag.
- Press `Shift` + `←` / `→` to expand or shrink the range.
- Press `Ctrl+A` key combination.
- `Space` when the tag is focused.
- Programmatic selection through the component [API](https://koobiq.io/api/tags.md).

Pointer and keyboard interactions change the same range relative to its initial tag. When the range shrinks, tags outside it are deselected. Disabled tags remain unchanged.

The selection option is configured using the `selectable` attribute (enabled by default).

### Editing

To enable editing mode, you need to set the `editable` property for `kbq-tag-list` or individual `kbq-tag`.

Enter editing mode:

- On double click on the tag.
- On pressing `Enter` or `F2` key (when tag is focused).

Save changes:

- On pressing `Enter` key.
- On clicking the confirmation button (`kbqTagEditSubmit` directive).

Cancel changes:

- On pressing `Escape` key.
- On focus loss.

In editing mode, the tag transforms into an input field and remains at the same position within the control.

[**Example: Tag autocomplete editable** (`tag-autocomplete-editable`)](https://koobiq.io/examples/tag-autocomplete-editable.md)

### Drag and drop

To enable tag reordering, you need to set the `draggable` property for `kbq-tag-list`.

[**Example: Tag autocomplete draggable** (`tag-autocomplete-draggable`)](https://koobiq.io/examples/tag-autocomplete-draggable.md)

### Validation

Validators belong on `<kbq-tag-list>`: the tag list is the form control for the whole set of tags, while the input is only a text entry helper.

A `[formControl]` or `[ngModel]` of its own on `<input kbqTagInputFor>` is still required here: `kbqAutocomplete` drives the input through it, and without it panel filtering and typed-text tracking break. The library simply does not consider validators attached to that control.

The control value is the array of tags, so a single set of validators covers both the number of tags and the content of each one. Validation applies equally to tags picked from the autocomplete panel, typed by hand and pasted from the clipboard.

Validators do not prevent a tag from being added: the tag is added and the field goes into the error state. To keep an invalid value out of the list, filter it in the `(kbqTagInputTokenEnd)` and `(optionSelected)` handlers.

When the error becomes visible is controlled by [ErrorStateMatcher](https://koobiq.io/en/other/validation.md), and by default happens once the control is invalid and either touched or the form has been submitted.

[**Example: Tag autocomplete with form control validators** (`tag-autocomplete-with-form-control-validators`)](https://koobiq.io/examples/tag-autocomplete-with-form-control-validators.md)

### Keyboard navigation

#### Focus in empty input area

| Key                         | Action                                         |
| --------------------------- | ---------------------------------------------- |
| Backspace / ← / Shift + Tab | Move focus to the last tag.                    |
| Ctrl + A                    | Select all tags and set focus to the last one. |

#### Focus on tag

| Key                | Action                           |
| ------------------ | -------------------------------- |
| ← / →              | Move focus to previous/next tag. |
| Shift + ← / →      | Change the range and move focus. |
| Space              | Select/deselect tag.             |
| Delete / Backspace | Remove tag.                      |
| F2 / Enter         | Start editing.                   |
| Ctrl + A           | Select all tags.                 |
| Home / End         | Move focus to first/last tag.    |

#### Tag editing mode

| Key   | Action          |
| ----- | --------------- |
| Enter | Save changes.   |
| Esc   | Cancel changes. |

## Examples

### Disable tag creation on the "paste" event

[**Example: Tag autocomplete onpaste off** (`tag-autocomplete-onpaste-off`)](https://koobiq.io/examples/tag-autocomplete-onpaste-off.md)
