Tag Input Component for Angular

This is a component for Angular >= 4. Design and API are blandly inspired by Angular Material's md-chips. Formerly called ng2-tag-input.

Demo

Check out the live demo.

NB: This repository is currently unmaintained. Please fork or use Angular Material's chips module, it got better.

Getting Started

npm i ngx-chips // OR
yarn add ngx-chips

Notice: the latest version on NPM may not reflect the branch master. Open an issue and tag me if you need it to be published.

Configuration

Ensure you import the module and the dependencies:

import { TagInputModule } from 'ngx-chips';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; // this is needed!
import { FormsModule, ReactiveFormsModule } from '@angular/forms';

@NgModule({
   imports: [
       TagInputModule, 
       BrowserAnimationsModule,
       FormsModule,
       ReactiveFormsModule
       ...OtherModules 
   ] // along with your other modules
})
export class AppModule {}

API for TagInputComponent

Inputs

ngModel OR use FormGroup/formControlName (required)

• ngModel - [string[] | TagModel[]] - Model of the component. Accepts an array of strings as input OR an array of objects.

If you do use an array of objects, make sure you:

• define two properties, value and display. Value will uniquely identify the items, display will be the value displayed.
• or, in alternative, provide the keys using the inputs identifyBy and displayBy

Notice: the items provided to the model won't change, but the items added to the model will have the format { display, value }. If you do provide identifyBy and displayBy, these will be used as format for the user-entered tags.

---

Properties (optional)

placeholder - [?string]

String that sets the placeholder of the input for entering new terms.

secondaryPlaceholder - [?string]

String that sets the placeholder of the input for entering new terms when there are 0 items entered.

maxItems - [?number]

Sets the maximum number of items it is possible to enter.

~~readonly~~ - [?boolean] [REMOVED]

Please add a readonly attribute to each tag model as a truthy value instead.

Example:

// TagModel
{
    display: 'display',
    value: 124242,
    readonly: true
}

separatorKeyCodes - [?number[]]

Array of keyboard keys with which is possible to define the key for separating terms. By default, only Enter is the defined key.

separatorKeys - [?string[]]

Array of input characters with which is possible to define the key for separating terms. Default is empty. Can use with separatorKeyCodes, either one method matched will trigger tag separation.

~~transform~~ - [?(item: string) => string] [REMOVED]

Please use onAdding instead. Just pass the value, transformed, to the Observable.

inputId - [?string]

Custom ID assigned to the input

inputClass - [?string]

Custom class assigned to the input

clearOnBlur - [?boolean]

If set to true, it will clear the form's text on blur events

hideForm - [?boolean]

If set to true, will remove the form from the component

onTextChangeDebounce - [?number]

Number of ms for debouncing the onTextChange event (defaults to 250)

addOnBlur - [?boolean]

If set to true, will add an item when the form is blurred (defaults to false)

addOnPaste - [?boolean]

If set to true, will add items pasted into the form's input (defaults to false)

pasteSplitPattern - [?string | RegExp]

Pattern used with the native method split() to separate patterns in the string pasted (defaults to ,)

blinkIfDupe - [?boolean]

If a duplicate item gets added, this will blink - giving the user a visual cue of where it is located (defaults to true)

removable - [?boolean]

If set to false, it will not be possible to remove tags (defaults to true)

editable (experimental) - [?boolean]

If set to true, it will be possible to edit the display value of the tags (defaults to false)

allowDupes - [?boolean]

If set to true, it will be possible to add tags with the same value (defaults to false)

modelAsStrings - [?boolean]

If set to true, all values added will be strings, and not objects (defaults to false)

trimTags - [?boolean]

If set to false, the tags could contain leading and trailing spaces (defaults to true)

inputText - [?string]

Property to bind text directly to the form's value. You can use it to change the text of the input at any time, or to just bind a value. Remember: use two-way data binding with this property.

ripple - [?boolean]

Specifies whether the ripple effect should be visible or not (defaults to true)

disable - [?boolean]

If set to true, the input will be disabled. Similar to readonly but with a visual effect.

Notice*: this attribute was changed from 'disabled' to 'disable' in order to comply with Angular's compiler.

tabindex - [?string]

If set, passes the specified tabindex to the form's input.

dragZone - [?string]

If set, the input will be draggable. Also the input will be draggable to another form with the same dragZone value.

animationDuration - [?{enter: string, leave: string}]

This option overwrites the default timing values for the animation. If you don't like the animation at all, just set both values to '0ms'.

The default value is {enter: '250ms', leave: '150ms'}

---

Validation (optional)

validators - [?ValidatorFn[]]

An array of Validators (custom or Angular's) that will validate the tag before adding it to the list of items. It is possible to use multiple validators.

asyncValidators - [?AsyncValidatorFn[]]

An array of AsyncValidators that will validate the tag before adding it to the list of items. It is possible to use multiple async validators.

errorMessages - [?Object{error: message}]

An object whose key is the name of the error (ex. required) and the value is the message you want to display to your users

onAdding - [?onAdding(tag: tagModel): Observable<TagModel>]

Hook to intercept when an item is being added. Needs to return an Observable.

• You can modify the tag being added during the interception.

Example:

 public onAdding(tag: TagModel): Observable<TagModel> {
    const confirm = window.confirm('Do you really want to add this tag?');
    return Observable
        .of(tag)
        .filter(() => confirm);
}

onRemoving - [?onRemoving(tag: tagModel): Observable<TagModel>]

Hook to intercept when an item is being removed. Needs to return an Observable. Example:

public onRemoving(tag: TagModel): Observable<TagModel> {
        const confirm = window.confirm('Do you really want to remove this tag?');
        return Observable
            .of(tag)
            .filter(() => confirm);
    }

---

Autocomplete (optional)

onlyFromAutocomplete - [?boolean]

If set to true, it will be possible to add new items only from the autocomplete dropdown

Tags as Objects (optional)

identifyBy - [?any]

Any value you want your tag object to be defined by (defaults to value)

displayBy - [?string]

The string displayed in a tag object (defaults to display)

---

Outputs (optional)

onAdd - [?onAdd($event: string)]

Event fired when an item has been added

onRemove - [?onRemove($event: string)]

Event fired when an item has been removed

onSelect - [?onSelect($event: string)]

Event fired when an item has been selected

onFocus - [?onFocus($event: string)]

Event fired when the input is focused - will return current input value

onBlur - [?onBlur($event: string)]

Event fired when the input is blurred - will return current input value

onTextChange - [?onTextChange($event: string)]

Event fired when the input value changes

onPaste - [?onPaste($event: string)]

Event fired when the text is pasted into the input (only if addOnPaste is set to true)

onValidationError - [?onValidationError($event: string)]

Event fired when the validation fails

onTagEdited - [?onTagEdited($event: TagModel)]

Event fired when a tag is edited

API for TagInputDropdownComponent

TagInputDropdownComponent is a proxy between ngx-chips and ng2-material-dropdown.

autocompleteObservable - [(text: string) => Observable<Response>]

A function that takes a string (current input value) and returns an Observable (ex. http.get()) with an array of items wit the same structure as autocompleteItems (see below). Make sure you retain the scope of your class or function when using this property. It can be used to populate the autocomplete with items coming from an async request.

showDropdownIfEmpty - [?boolean]

If set to true, the dropdown of the autocomplete will be shown as soon as the user focuses on the form

keepOpen - [?boolean]

To use in conjunction with showDropdownIfEmpty. If set to false, the dropdown will not reopen automatically after adding a new tag. (defaults to true).

autocompleteItems - [**`?string[] | AutoCompl