Tag InputPro
Pro
Tag Input enables users to add multiple tags or select multiple users from a dropdown. It supports autocomplete, keyboard navigation, and can display items with or without avatars.
Tag Input Playground
Tag Input Playground
Preview
Code
Select from available options
Controls
Type:
Tags
Users
Size:
Small
Default
Large
Status:
Default
Error
Success
Disabled:
Read Only:
Leading:
Trailing:
Installation
You can add the tag input component to your project manually:
1
Install the following dependencies:
npm
pnpm
yarn
bun
npm install class-variance-authority clsx tailwind-merge @phosphor-icons/react @react-aria/button @react-aria/focus @react-aria/interactions2
Copy and paste the following code into your project.
Loading...
3
Update the import paths to match your project setup.
Update the import aliases (e.g. @/components, @/utils) in the copied files to match your project's path configuration.
Basic Usage
A simple tag input with default options:
import { TagInput } from '@versaui/ui/components/TagInput';
<TagInput placeholder="Add Tags" />Types
Tags
The default type displays text-only tags:
<TagInput type="tags" placeholder="Add Tags" />Users
Set type="users" for avatar-based user selection:
<TagInput type="users" placeholder="Add Users" />Controlled State
For external state control, use value and onChange:
import { useState } from 'react';
import { TagInput, type TagValue } from '@versaui/ui/components/TagInput';
function ControlledExample() {
const [values, setValues] = useState<TagValue[]>([]);
return (
<TagInput
value={values}
onChange={setValues}
placeholder="Add Tags"
/>
);
}Sizes
Three sizes are available — small, default, and large:
<TagInput size="small" placeholder="Small" />
<TagInput size="default" placeholder="Default" />
<TagInput size="large" placeholder="Large" />Status States
Set status to show validation states:
<TagInput status="default" placeholder="Default state" />
<TagInput status="error" errorText="Please select at least one option" />
<TagInput status="success" helperText="Great choice!" />Custom Options
Provide custom options for the dropdown:
const myOptions = [
{ id: 'react', label: 'React' },
{ id: 'vue', label: 'Vue' },
{ id: 'angular', label: 'Angular' },
];
<TagInput options={myOptions} placeholder="Select framework" />Max Tags
Limit the number of selectable tags:
<TagInput maxTags={3} helperText="Maximum 3 tags allowed" />Disabled and Read-Only
<TagInput disabled placeholder="Disabled" />
<TagInput readOnly defaultValue={[{ id: '1', label: 'Read Only' }]} />Accessibility
- Keyboard navigation: Arrow keys navigate options, Enter selects, Backspace removes last tag, Escape closes dropdown
- Screen readers: Uses proper ARIA roles for combobox pattern
- Focus management: Clear focus indicators and trap
- Semantic structure: Uses
role="combobox"with properaria-expandedandaria-controls
TagInput Props
| Prop | Type | Default | Description |
|---|---|---|---|
type | 'tags' | 'users' | 'tags' | Type of input — tags for text-only, users for avatar-based. |
size | 'small' | 'default' | 'large' | 'default' | Size variant. |
value | TagValue[] | — | Controlled value array. |
defaultValue | TagValue[] | [] | Initial value for uncontrolled mode. |
onChange | (values: TagValue[]) => void | — | Callback when values change. |
options | TagOption[] | — | Available options to select from. |
onSearch | (query: string) => void | — | Callback for search input (async search). |
placeholder | string | 'Add Tags' or 'Add Users' | Placeholder text. |
helperText | string | — | Helper text below input. |
errorText | string | — | Error text (overrides helperText when present). |
status | 'default' | 'error' | 'success' | 'default' | Status state. |
disabled | boolean | false | Disabled state. |
readOnly | boolean | false | Read-only state. |
maxTags | number | — | Maximum number of tags allowed. |
showLeadingItem | boolean | true | Show leading icon or avatar. |
showTrailingItem | boolean | true | Show trailing icon area. |
leadingIcon | ReactNode | CirclesFourIcon | Custom leading icon (tags type only). |
trailingIcon | ReactNode | InfoIcon | Custom trailing icon. |