@rozie-ui/tags-angular

Idiomatic angular Tags — a headless, fully-accessible (WAI-ARIA) tags / token input (removable chips, type-to-add with configurable delimiters, paste-to-bulk-add, dedup, per-token validation, a max cap, and a scoped #tag slot for custom chip rendering) compiled from one Rozie source. The interaction engine IS the browser's native <input> plus the platform clipboard/keyboard; every visual value is a CSS custom property, so it re-skins to any design system. This package is generated; do not edit src/ by hand.

Install

npm i @rozie-ui/tags-angular

Peer dependencies: @angular/core + @angular/common + @angular/forms. Install them alongside this package.

Also installed: @rozie/runtime-angular — Rozie's small, tree-shaken runtime helper package (controllable state, keyboard navigation, event modifiers, and safe interpolation). It arrives as a regular dependency, so npm pulls it for you. Your bundler keeps only the helpers this component actually uses — typically a few hundred bytes to a few KB, minified and gzipped. What's in it and what it costs.

Usage

import { Component } from '@angular/core';
import { Tags } from '@rozie-ui/tags-angular';

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [Tags],
  template: `
    <rozie-tags
      [(modelValue)]="skills"
      placeholder="Add a skill…"
      ariaLabel="Skills"
      [max]="8"
      (add)="onAdd($event)"
    />
  `,
})
export class DemoComponent {
  skills = ['rozie', 'angular'];
  // The `add` output is typed `unknown`; its payload is { value, tokens }.
  onAdd(e: unknown) {
    console.log('added', (e as { value: string; tokens: string[] }).value);
  }
}

Theming

Every visual value is a --rozie-tags-* CSS custom property — override any of them at any ancestor scope. Ready-made design-system bridges ship in the package:

import '@rozie-ui/tags-angular/themes/shadcn.css';    // or material.css, bootstrap.css, base.css

Angular forms

The generated class implements ControlValueAccessor — the modelValue model prop is the control value, so a tags input is a form control. It binds to template-driven and reactive forms directives directly, with no wrapper directive:

import { Component } from '@angular/core';
import { ReactiveFormsModule, FormControl } from '@angular/forms';
import { Tags } from '@rozie-ui/tags-angular';

@Component({
  selector: 'app-tags-form',
  standalone: true,
  imports: [Tags, ReactiveFormsModule],
  template: `
    <!-- The tokens array IS the form control value -->
    <rozie-tags [formControl]="skills" ariaLabel="Skills" [max]="8" />
  `,
})
export class TagsFormComponent {
  skills = new FormControl<string[]>(['rozie']);
}

// Template-driven forms work the same way:
//   <rozie-tags [(ngModel)]="skills" name="skills" />

Props

| Name | Type | Default | Two-way (model) | Required | Description | | --- | --- | --- | :---: | :---: | --- | | modelValue | Array | [] | ✓ | | The committed tokens — model: true, so a commit/remove/paste writes a fresh array back through r-model:modelValue (uncontrolled fallback []). Because it is the sole model prop, the Angular output is a ControlValueAccessor ([formControl] / [(ngModel)] bind directly). | | delimiters | Array | […] | | | The keys that commit the current draft as a token (matched against the key event's key). Default [',', 'Enter']. Non-'Enter' entries also act as the split characters when pasting bulk text: a paste containing one is split and every part is added, and the parts that are rejected (by validate or max) are inserted at the caret, so the typed draft is kept. A paste with no split character is ordinary text. Use e.g. [' ', 'Enter'] for a space-delimited input. | | allowDuplicates | Boolean | false | | | Allow the same token value to be added more than once. Defaults to false — a candidate equal (case-sensitive) to an existing token is silently rejected on commit. Set true to permit duplicates. | | max | Number | null | | | Maximum number of tokens. Once the list reaches max, the input is disabled and further adds (type, paste, programmatic) are rejected. null (the default) means unlimited. | | disabled | Boolean | false | | | Disable the whole control — the text input is disabled, every remove button is disabled, and no token can be added or removed. Also sets the Angular CVA disabled state. | | readonly | Boolean | false | | | Render the tokens read-only — they remain visible but cannot be added or removed, and the text input is hidden. Unlike disabled it carries no disabled styling, so it reads as a display of committed values. | | validate | Function | null | | | Optional per-token validator / normalizer. Called with (candidate, tokens) for each commit; return a (possibly normalized) string to accept it, or a falsy value (false / null / "") to reject the candidate. Runs before the dedup + max checks. Example: v => /^\S+@\S+$/.test(v) ? v.toLowerCase() : false for emails. | | placeholder | String | '' | | | Placeholder text for the inline text input (e.g. "Add a tag…"). | | ariaLabel | String | null | | | Accessible name for the whole control (role="group"). The inline text input is labelled with the same name so assistive tech announces what is being entered. A visually-hidden live region announces the current token count on change. |

Events

| Event | Description | | --- | --- | | change | Fired on every committed-list mutation (add, remove, paste-bulk-add, or a programmatic clear). Payload { value } — the new full tokens array. Use it to observe the list without two-way binding. | | add | Fired when a token is committed (an accepted Enter/comma/paste add). Payload { value, tokens } — value is the newly added token string, tokens the fresh full array. Rejected candidates (duplicate, failed validate, over max) do NOT fire it. | | remove | Fired when a token is removed (a chip remove-button click or Backspace in an empty input). Payload { value, index, tokens } — the removed token, its former index, and the fresh full array. |

Imperative handle

Beyond props, the component exposes imperative methods (declared once in the Rozie source via $expose). Grab a handle with the native ref mechanism and call them directly:

| Method | Description | | --- | --- | | clear | Remove every token (emits change with { value: [] }) and move DOM focus to the text input. Collision-safe — not a host-element member. | | focus | Move DOM focus to the inline text input. NOTE: this deliberately overrides the inherited HTMLElement.focus on the Lit custom element (ROZ137 warns, warn-only) — the public focus() handle is the intended semantics. |

@Component({ /* ... */ })
export class DemoComponent {
  @ViewChild(Tags) tags!: Tags;   // or the viewChild() signal
  focusIt() { this.tags.focus(); }
  clearIt() { this.tags.clear(); }
}

Slots

| Slot | Params | | --- | --- | | tag | tag, index, remove |

The scoped tag slot lets you fully replace each chip; its params are { tag, index, remove } (the token string, its index, and a zero-arg remove() for that token). On React the slot is a render-prop children callback (the documented cross-framework slot divergence).