- ⚡ [Autosuggest](#auto-suggest) with **fuzzy matching** for smarter suggestions (type "many" to find "Germany")
- ♿ **WCAG 2.1 AA Accessible** - ARIA support, keyboard navigation, screen reader announcements
- ⌨️ **Advanced keyboard navigation** - Arrow keys, Home/End, Tab, Escape fully supported
- ✏️ [Edit](#editable-tags) the tags inline by double clicking them.
- 🏷️ [Paste](#paste) strings with delimiters of your choice and the component will create the tags for you.
- 🗑️ Quickly delete the tags with a visual confirmation before removing a tag.
- 🧹 Quickly clear all tags with `quick-delete` mode.
- 🔒 [Lock the component](#readonly-tags) using the `readonly` mode.
- ✋ [Restrict](#max-tags) the number of tags and Handle duplicates gracefully.
- 🌈 [Customize](#theme) the colors.
- 📱 **Mobile optimized** - 44px touch targets, responsive layout, virtual keyboard support
- 🎯 **Intelligent error handling** - Real-time error messages, empty states, result counts
### Table of Contents
- [⚡ Installation](#-installation)
- [🚀 Getting Started](#-getting-started)
- [🎯 Nuxt 3 Support](#-nuxt-3-support)
- [🍬 Demos](#-demos)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Accessibility](#accessibility)
- [Props](#props)
- [Default Tags](#default-tags)
- [Duplicates](#duplicates)
- [Auto Suggest](#auto-suggest)
- [Max Tags](#max-tags)
- [Paste](#paste)
- [Editable Tags](#editable-tags)
- [Readonly Tags](#readonly-tags)
- [Theme](#theme)
- [Custom Class names](#custom-class-names)
- [Migration Guide (v0.5.0+)](#migration-guide-v050)
- [📦 Build Setup](#-build-setup)
- [🔨 Contributing](#-contributing)
- [Notes](#notes)
- [Meta](#meta)
## ⚡ Installation
```bash
# Using npm
npm install smart-tagz
# Using yarn
yarn add smart-tagz
# Using pnpm
pnpm add smart-tagz
```
## 🚀 Getting Started
smart-tagz has some great defaults to get you started quickly. Please check the props list for all options.
```jsx
```
## 🎯 Nuxt 3 Support
Smart-Tagz works seamlessly with **Nuxt 3**! We provide an official Nuxt 3 module for easy integration.
### Quick Setup
#### Option 1: Using the Nuxt Module (Recommended)
```bash
npm install smart-tagz
```
Add to `nuxt.config.ts`:
```typescript
export default defineNuxtConfig({
modules: [
'smart-tagz/nuxt'
]
})
```
Use it in your components:
```vue
```
#### Option 2: Manual Plugin Setup
Create a plugin file `plugins/smart-tagz.ts`:
```typescript
import { defineNuxtPlugin } from '#app'
import SmartTagz from 'smart-tagz'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.component('SmartTagz', SmartTagz)
})
```
### Key Features in Nuxt 3
- ✅ Full SSR/SSG support
- ✅ Auto-imported components (via Nuxt module)
- ✅ TypeScript support
- ✅ Reactive source updates
- ✅ Programmatic control via refs
- ✅ All Vue 3 Composition API features supported
### Common Patterns
**Programmatic Tag Control**:
```vue
```
**Async Data Loading**:
```vue
```
For complete Nuxt 3 documentation, see the [Nuxt 3 Guide](https://smart-tagz.vercel.app/guide/nuxt3) or check the [docs](./docs/guide/nuxt3.md).
## 🍬 Demos
Head to our demo page for examples showcasing all the features.
[https://smart-tagz.vercel.app/](https://smart-tagz.vercel.app/)
## ⌨️ Keyboard Shortcuts
Smart-Tagz supports full keyboard navigation for accessibility and efficiency:
| Key | Action |
|-----|--------|
| ↑ / ↓ | Navigate suggestions up/down |
| Home | Jump to first suggestion |
| End | Jump to last suggestion |
| Enter | Select highlighted suggestion or add typed text |
| Tab | Select highlighted suggestion and move focus |
| Escape | Close suggestions and clear selection |
| Backspace | Delete character or last tag when input is empty |
| Delete | Delete last tag (press again to confirm) |
| Ctrl + A | Select all tags for quick deletion (when `quickDelete` enabled) |
## ♿ Accessibility
Smart-Tagz is built with **WCAG 2.1 Level AA** compliance in mind:
### Features
- **ARIA Support**: Proper roles (`combobox`, `listbox`, `option`) and attributes (`aria-expanded`, `aria-selected`, `aria-label`)
- **Screen Reader Announcements**:
- Tag additions: "France added. 3 of 20 tags"
- Tag removals: "Germany removed. 2 of 20 tags"
- Error states: "Maximum 20 tags allowed"
- Filtered results: Announced via live region
- **Keyboard Navigation**: All interactions possible without mouse
- **Focus Management**: Visible focus indicators on all interactive elements
- **Semantic HTML**: Proper use of `
`, `
` for suggestions
- **Color Independence**: Error states use icons and text, not color alone
### Testing with Screen Readers
- **Windows**: NVDA (free), JAWS
- **macOS**: VoiceOver (built-in)
- **iOS**: VoiceOver (built-in)
- **Android**: TalkBack (built-in)
### Example with Screen Reader Announcements
```vue
```
## Props
| Prop | Type | Description | Default |
| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------ | ---------------- |
| defaultTags | Array | initialize with a `default` set of tags | [] |
| width | String | `width` of the container | 100% |
| autosuggest | Boolean | Enables the `autosuggest` feature. you also need to set the sources for the autosuggest to work. | false |
| sources | Array | Works as the `datasource` for the autosuggest feature | [] |
| allowPaste | { delimiter: String } | Parses the pasted string based on the passed delimiter and creates tags automatically | {delimiter: ","} |
| editable | Boolean | makes the tags `editable` | false |
| allowDuplicates | Boolean | allows/disallows `duplicate` tag entries while pasted or entered manually. | true |
| maxTags | Number | sets the `Maximum` number of tags | 20 |
| inputPlaceholder | String | `Placeholder` for the input box. | "Enter tag..." |
| readOnly | Boolean | Makes the whole component `readOnly`. ideal for display only purposes. | false |
| quick-delete | Boolean | When enabled all the tags can be cleared by CTRL + A, DEL | false |
| on-changed | Function | `callback` that gets called when a new tag is added or an existing tag is deleted | false |
> **Note:** Props can be passed using either camelCase (`quickDelete`) or kebab-case (`:quick-delete`) in Vue templates. The table uses kebab-case for consistency with HTML attribute conventions.
### Default Tags
We can initialize smart-tagz with some `default` tags. This setting will mostly be used along with the `readonly` prop to create tags for display only purposes.
```jsx
```
### Duplicates
You can decide how to manage `duplicate` tags by either allowing or disallowing them completely. When set to `false` no duplicate values are allowed.
```jsx
```
### Auto Suggest
When set to `true`, the `autosuggest` prop suggests values in a dropdown using **smart fuzzy matching**. You also need to set the `sources` prop for this to work. The `sources` prop can be an Array of strings.
#### Fuzzy Matching
Smart-Tagz uses intelligent fuzzy matching powered by [fuse.js](https://fusejs.io/) to provide flexible searching:
- **Smart matching**: Type "many" to find "Germany", "germ" to find "Germany", etc.
- **Typo tolerance**: Slightly misspelled words still match
- **Partial matching**: Match any part of the word, not just the beginning
- **Real-time results**: Suggestions update as you type with result count
```jsx
```
#### Visual Feedback
- **Result highlighting**: Matching characters are highlighted in yellow
- **Result count**: Shows "3 results" or "1 result" above suggestions
- **Empty state**: Shows "No matches found for 'xyz'" when nothing matches
### Max Tags
The component can also be configured to accept the `Maximum` number of tags that can be created. Once the threshold is reached, the input will be `hidden` from the user.
Here we restrict the tags to `3`
```jsx
```
### Paste
The component can parse strings and automatically create tags for you. The default delimiter is `","` but you can override this setting by manually setting the `delimiter` option.
```jsx
```
### Editable Tags
The Tags are not `editable` by default, but you can change this setting with the `editable` prop. Simply double click a tag, make the changes and hit enter to save.
```jsx
```
### Readonly Tags
You can lock the component with `readonly` mode. All interactions are disabled in `read-only` mode.
```jsx
```
### Theme
The components color scheme can be customized by passing a custom theme prop.
```jsx
```
**Theme Properties:**
- `primary` (String, required): Main color for tag background and suggestion pane
- `tagTextColor` (String, required): Text color for tags
- `background` (String, optional): Container background color
- `secondary` (String, optional): Additional accent color (currently unused)
### Custom Class names
If you are looking for more control in terms of customizing the style of the tags, you can make use of the `classNames` prop to apply custom classes to the different elements within the component.
```jsx
```
## 🚀 Migration Guide (v0.5.0+)
### Breaking Changes
#### 1. Fuzzy Matching (Default Behavior Change)
**Before (v0.4.x)**: Prefix-only matching
```
Input: "many" → Suggestions: (no results)
```
**After (v0.5.0+)**: Smart fuzzy matching
```
Input: "many" → Suggestions: ["Germany", "Myanmar"]
```
**Migration**: Update your tests and documentation to reflect fuzzy matching behavior. No code changes required unless you relied on prefix-only behavior.
#### 2. New Dependency: fuse.js
**Added**: `fuse.js` (~7KB gzipped) for fuzzy search
- Already included in package.json
- No configuration needed
- Improves search quality automatically
#### 3. CSS Class Changes
New utility class added:
```scss
.sr-only // Screen reader only text (hidden visually, visible to screen readers)
```
Updated styles:
- `.suggest-pane-item`: Font size reduced from `var(--font-size-sm)` to `0.9rem`
- `.suggest-pane-item--selected`: Added left border (3px) indicator
- `.suggest-pane-item`: Added 600 font-weight for better hierarchy
#### 4. Tag Close Button Size
**Before**: ~16px
**After**: **44px** (iOS HIG minimum, better mobile accessibility)
May affect layouts that assumed smaller buttons. Adjust styles if needed:
```scss
.tag-container__button {
// Now: width: 44px; height: 44px;
// Override if needed:
@include size(24px); // your size here
}
```
#### 5. New ARIA Attributes
Added for accessibility. No breaking changes, but updated DOM structure:
```html
...
```
### New Features (Non-Breaking)
✅ Screen reader announcements for tag operations
✅ Live error messages (duplicate/max tags)
✅ Empty state messaging ("No matches found")
✅ Result count indicator
✅ Result highlighting in suggestions
✅ Enhanced keyboard navigation (Home, End, Tab)
✅ Mobile-optimized touch targets
✅ Responsive dropdown height (80vh on desktop, 60vh on mobile)
✅ Better focus indicators with `:focus-visible`
### Upgrade Checklist
- [ ] Review fuzzy matching behavior in your use cases
- [ ] Test with keyboard navigation (arrows, Home, End, Tab)
- [ ] Test with screen readers (optional but recommended)
- [ ] Verify button sizes in your layout
- [ ] Update unit tests for new matching behavior
- [ ] Update documentation for end users
## 📦 Dependencies
Smart-Tagz uses the following core dependencies:
| Package | Version | Purpose |
|---------|---------|---------|
| **fuse.js** | ^7.1.0 | Fuzzy search and matching for autosuggest feature |
| **vue-feather-icons** | ^5.1.0 | Icon components (peer dependency) |
| **escape-string-regexp** | ^5.0.0 | Utility for escaping special characters in regex patterns |
| **shiki** | ^3.15.0 | Syntax highlighting for code blocks in demo (demo-only) |
> **Note:** `vue-feather-icons` is a peer dependency, so it must be installed separately in your project.
## 📦 Build Setup
```bash
# install dependencies (using pnpm)
pnpm install
# start dev
pnpm dev
# build library
pnpm build
# run css linting
pnpm lint:css
# run css linting and fix
pnpm lint:css:fix
# run all tests
pnpm test
# run tests with coverage
pnpm test:coverage
```
**Note:** The project uses pnpm for dependency management. You can also use npm or yarn, but pnpm is recommended.
## 🔨 Contributing
1. Fork it ( [https://github.com/prabhuignoto/smart-tagz/fork](https://github.com/prabhuignoto/smart-tagz/fork) )
2. Create your feature branch (`git checkout -b new-feature`)
3. Commit your changes (`git commit -am 'Add feature'`)
4. Push to the branch (`git push origin new-feature`)
5. Create a new Pull Request
## Notes
The project uses [vite](vite) instead of @vue/cli. I choose vite for speed and i also believe [vite](vite) will be the future.
## Meta
Prabhu Murthy – [@prabhumurthy2](https://twitter.com/prabhumurthy2) – prabhu.m.murthy@gmail.com
Distributed under the MIT license. See `LICENSE` for more information.
[https://github.com/prabhuignoto/](https://github.com/prabhuignoto/)
[vue]: https://vuejs.org
[typescript]: https://typescriptlang.org
[vite]: https://github.com/vitejs/vite
---
_Source: https://npm.io/package/smart-tagz · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
