@botandrose/input-tag

A declarative, framework-agnostic custom element for tag input with optional autocomplete functionality.

Built with appreciation on the excellent foundation of Taggle.js by Sean Coker.

Installation

npm install @botandrose/input-tag

Usage

Import the custom element:

import "@botandrose/input-tag"

Then use it in your HTML:

<input-tag name="tags" multiple>
  <tag-option value="javascript">JavaScript</tag-option>
  <tag-option value="typescript">TypeScript</tag-option>
</input-tag>

<datalist id="suggestions">
  <option value="react">React</option>
  <option value="vue">Vue</option>
  <option value="angular">Angular</option>
</datalist>

<input-tag name="frameworks" list="suggestions" multiple></input-tag>

Features

• Form-associated custom element with full form integration
• Autocomplete support via datalist or custom options
• Multiple/single value modes
• Real-time validation
• Accessible keyboard navigation
• Shadow DOM encapsulation
• Framework-agnostic

API

Attributes

• name: Form field name
• multiple: Allow multiple tags (default: single tag mode)
• required: Make field required
• list: ID of datalist for autocomplete suggestions

Properties

• value: Get/set tag values - returns array when multiple, string when single mode
• tags: Get current tag values as array (read-only)
• options: Get available autocomplete options from datalist
• form: Reference to associated form element
• name: Get the name attribute value

Events

• change: Fired when tag values change
• update: Fired when individual tags are added/removed with detail {tag, isNew}

Methods

Tag Management

• add(tag | tags[]): Add single tag or array of tags
• remove(tag): Remove specific tag by value
• removeAll(): Clear all tags
• has(tag): Check if tag exists
• addAt(tag, index): Add tag at specific position

Form Integration

• reset(): Clear all tags and input field
• checkValidity(): Check if field passes validation
• reportValidity(): Check validity and show validation UI

Interaction

• focus(): Focus the input field
• disable(): Disable the input
• enable(): Enable the input

JavaScript API Example

// Multiple mode
const multipleTag = document.querySelector('input-tag[multiple]')

// Add tags
multipleTag.add('react')
multipleTag.add(['vue', 'angular'])

// Get current tags
console.log(multipleTag.value) // ['react', 'vue', 'angular'] - returns array
console.log(multipleTag.tags)  // ['react', 'vue', 'angular'] - also array

// Set all tags at once
multipleTag.value = ['new', 'tags'] // accepts array

// Single mode
const singleTag = document.querySelector('input-tag:not([multiple])')

// Set single tag
singleTag.value = 'selected-tag' // accepts string

// Get current tag
console.log(singleTag.value) // 'selected-tag' - returns string
console.log(singleTag.tags)  // ['selected-tag'] - always array

// Backward compatibility: arrays still work in single mode
singleTag.value = ['another-tag'] // accepts array, uses first item
console.log(singleTag.value) // 'another-tag' - still returns string

// Form validation
if (!singleTag.checkValidity()) {
  singleTag.reportValidity()
}

Testing

npm test
npm run test:all

License

MIT