AngularTagsInput (@iomechs/angular-tags-input)

A simple tags input library for Angular. Supports nested elements and a lot of flexibility to the developers. (README to be updated)

Installation

Install the package in your project's folder by using npm or yarn:

npm install @iomechs/angular-tags-input --save
# OR
yarn add @iomechs/angular-tags-input -S

Getting Started

Import AngularTagsInputModule in your AppModule as below:

import { AngularTagsInputModule } from '@iomechs/angular-tags-input';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    BrowserAnimationsModule,
    AngularTagsInputModule, // <-- here
  ]
});

Then in your HTML, you can use as:

<ti-angular-tags-input formControlName="locations" [tagsData]="(data$ | async)" (valueChanged)="onTagInputValueChange($event)" [config]="tagsInputConfig"> </ti-angular-tags-input>

Input Properties

These are the available Input properties you can pass to the component.

| Input | Type | Default | Description | | ------ | ----- | -----| --------------- | | tagsData | any[] | [] | List of items to be added in dropdown. Must be piped with async to pass an array. | | disabled | boolean | false | Disables the component interactions. | | config | AngularTagsInputConfig | (described in Interfaces section) | Component configuration (defined in AngularTagsInputConfig under Configuration Interface) | | dropDownTemplate | TemplateRef<any> | Built-in template | Template used for rendering the dropdown content. | | tagItemTemplate| TemplateRef<any> | Built-in template | Template used for rendering the tag item in field.|

Ouput Events

These events are emitted by the component and can be subscribed to using Angular event binding syntax.

| Output | Payload Type | Description | | -------------- | ------------- | -----------| | tagAdded | Tag item object (original data + internal metadata) | Emitted when a new tag is added | | tagRemoved | Tag item object (original data + internal metadata) | Emitted when a tag is removed | | valueChanged | string d| Emit the value typed in input field | | itemClicked | Tag item object (original data + internal metadata) | Emit when a tag is clicked. |

Note: The emitted item in tagAdded, tagRemoved and itemClicked includes all properties of your original data object, along with additional internal fields used by the library (e.g., tiSelected, tiIdentifier, etc.).

Configuration Interface

AngularTagsInputConfig

This interface defines all configurable options available for the tags input component.

| Option | Type | Description | | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | identifier | string | Unique key used to identify each item in the provided tagsData. | | displayProperty | string | Key in your tagsData whose value will be shown as the label for each dropdown option. | | showTooltipOnOptions | boolean | Shows tooltip on hovering the dropdown options. Should be used together with hoverProperty. | | hoverProperty | string | The value that will be displayed as tooltip. | | showTagsSelectedInDD | boolean | Enable it if you want to show a check mark on selected items. | | hideAddedTags | boolean | Enable it if you want to hide those tags that have already been selected in dropdown. | | placeholder | string | The placeholder value for input field. | | additionalClasses | string | Additional classes to style input field. | | hideDDOnTagSelect | boolean | Enable it if you want to hide dropdown on every tag selection. | | toggleSelectionOnClick | boolean | Allows selecting/deselecting a dropdown item on click; clicking an already-selected item removes it instead of adding again. | | clearInputOnFocus | boolean | Allows you to erase the text, when you focus on the input field. | | clearTagsOnFocus | boolean | Allows you to erase the tags, when you focus on the input field. | | ddHasBackdrop | boolean | Adds a backdrop overlay behind the dropdown | | hideDDOnBlur | boolean | Automatically hides the dropdown when the input field loses focus. Works only when ddHasBackdrop is disabled, because the backdrop prevents normal blur events. | | maxItems | number | Specify the max number of tags that can be added inside input field. | | hideInputOnSelection | boolean | Allows you to insert only one tag, as the input field disappears on tag selection. | | hideTags | boolean | Allows you to hide the selected tags from the input field. |

If your data is nested, you may need to use these options as well.

| Option | Type | Description | | ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | childrenCountProperty | number | Specifies the number of children an item have. | | nestedTagProperty | string | The key in your tagsData that have the list of child items. | | nestedTagParentProp | string | Speicifies the identifer of parent. | | showParentTagsOnly | boolean | Enable it if you want to show only parent tag if all of its child tags are selected. Disable it if you want to show parent tags along with its child tags. |

Custom Templates

The component allows you to fully customize the dropdown and tag appearance by passing your own Angular templates. If you don't pass dropDownTemplate or tagItemTemplate, the library would use its own default template.

Dropdown Template (dropDownTemplate)

Example usages of dropDownTemplate are as follows:

Simple Dropdown Template

<ng-template #simpleDDTemplate let-items="items" let-config="config" let-fns="fns">
  <div *ngIf="items.length" style="max-height: 250px; overflow-y: auto; padding-top: 8px;">
    <div *ngFor="let item of items">
      <div (click)="fns.onItemClicked(item)" style="display: flex; justify-content: space-between;">{{item[config.displayProperty]}}</div>
      <div *ngIf="item.tiSelected && config.showTagsSelectedInDD">
        <img src="assets/tick.png" alt="tick" width="14" />
      </div>
    </div>
  </div>
</ng-template>

Note: Always remember to add (click)="fns.onItemClicked(item)", otherwise neither the item will be added in input field nor any event would be emitted on clicking item.

Don't forget to add tick.png in your assets folder.

Nested Dropdown Template

<ng-template #nestedDDTemplate let-items="items" let-config="config" let-fns="fns">
  <div *ngIf="items.length" style="max-height: 250px; overflow-y: auto;padding-top: 8px;">
    <div *ngFor="let item of items">
      <div (click)="fns.onItemClicked(item)" style="display: flex; justify-content: space-between;">
        {{item[config.displayProperty]}}
        <div *ngIf="item.tiSelected && config.showTagsSelectedInDD">
          <img src="/assets/tick.png" alt="tick" width="14" />
        </div>
      </div>
      <ng-container *ngTemplateOutlet="ddNestedChildrenTemplate; context: {items: item[config.nestedTagProperty], config: config, fns: fns}"> </ng-container>
    </div>
  </div>
</ng-template>

<ng-template #nestedDDChildTemplate let-items="items" let-fns="fns" let-config="config">
  <div style="margin-left: 16px;">
    <ng-container *ngFor="let item of items">
      <div (click)="fns.onItemClicked(item, $event)">
        <div>
          <div>{{item[config.displayProperty]}}</div>
          <div *ngIf="item.tiSelected && config.showTagsSelectedInDD">
            <img src="../assets/tick.png" alt="tick" width="14" />
          </div>
        </div>
        <ng-container *ngTemplateOutlet="nestedDDChildTemplate; context: {items: item[config.nestedTagProperty], config: config, fns: fns}"> </ng-container>
      </div>
    </ng-container>
  </div>
</ng-template>

Dropdown Template with Tooltip

<ng-template #simpleDDWithTooltip let-items="items" let-config="config" let-fns="fns">
  <div *ngIf="items.length" style="max-height: 250px; overflow-y: auto;padding-top: 8px;">
    <div *ngFor="let item of items">
      <div (click)="fns.onItemClicked(item)" style="display: flex; justify-content: space-between;" cdkOverlayOrigin #onHoverTrigger="cdkOverlayOrigin" (mouseenter)="fns.showTooltip(item[config.hoverProperty], onHoverTrigger)" (mouseleave)="fns.hideTooltip()">
        {{item[config.displayProperty]}}
        <div *ngIf="item.tiSelected && config.showTagsSelectedInDD">
          <img src="/assets/tick.png" alt="tick" width="14" />
        </div>
      </div>
    </div>
  </div>
</ng-template>

Tag Item Template (tagItemTemplate)

Example usage of tagItemTemplate is as follows

<ng-template
  #customTag
  let-item="item"
  let-config="config"
  let-closeClicked="closeClicked"
>
<div
  *ngIf="item"
  style="padding: 10px; background-color: black; color: white; display: flex; gap:8px; align-items: center; border-radius: 4px; margin-right: 4px;"
>
  <div>
    {{ item[config.displayProperty] }}
  </div>
  <button (click)="closeClicked.emit(item)"
    style="background: none; border: none; color: white; cursor: pointer; padding: 2px;">
    x
  </button>
</div>
</ng-template>  

Notice the (click)="closeClicked.emit(item)". If you don't include this in button tag, then the tag won't be removed from input field upon clicking on cross button and you will have to remove the item by clicking on option from dropdown.

If you don't want the cross button functionality, you can simply remove the button tag.

Compatibility

All released versions of this library (up to tag 0.1.16) are compatible with Angular ^8.2.11.

Use 1.x.x for Angular ^15.x.x

Development

Build

Run npm run build:lib to build the library. The build artifactsqm will be stored in the dist/ directory.

Running unit tests

Run npm test to execute the unit tests via Jest.

Release

1. Bump the version in projects/angular-tags-input/package.json.
2. Run npm install to update package-lock.json.
3. Commit the changes.
4. Tag the release: git tag -a v1.x.x -m "v1.x.x" (e.g., v1.1.0).
5. Push changes and tags: git push origin master --tags.
6. Run npm run release to build and publish the library to npm.

Demo

The demo application is located in projects/tags-input-demo.

Running the demo

Run npm start to serve the demo application. Navigate to http://localhost:4200/.

Deploying the demo

The demo is deployed to GitHub Pages using GitHub Actions. To deploy manually:

1. Run npm run build to build the demo application.
2. Deploy the contents of dist/tags-input-demo to the gh-pages branch.