## Overview [#overview]
`TagInput` lets users add, remove, and select multiple tags. It supports predefined options, free-typed tags via Enter/comma, CSV/TSV/newline pasting, and backspace-to-remove on an empty input.
## Usage [#usage]
```tsx
import { TagInput } from "@tilt-legal/cubitt-components/primitives";
const options = [
{ id: "react", label: "React" },
{ id: "ts", label: "TypeScript" },
{ id: "ui", label: "UI/UX" },
];
export default function Component() {
return ;
}
```
Sync tags with the URL by providing `paramName`. The component serializes to a string array automatically.
```tsx
// Synced with ?demo-tags=foo,bar (when tags are added)
// Advanced options
console.log("tags:", value)}
/>
```
## Examples [#examples]
### Default (predefined options) [#default-predefined-options]
```tsx
import { TagInput } from "@tilt-legal/cubitt-components/primitives";
const options = [
{ id: "react", label: "React" },
{ id: "ts", label: "TypeScript" },
{ id: "ui", label: "UI/UX" },
];
export default function Component() {
return ;
}
```
### Free entry + remove last on backspace [#free-entry--remove-last-on-backspace]
```tsx
import { useState } from "react";
import { TagInput } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
const [tags, setTags] = useState([]);
return (
);
}
```
### Paste CSV/TSV/newlines [#paste-csvtsvnewlines]
```tsx
import { TagInput } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
### Expanded field [#expanded-field]
Increase the field height when tags are likely to wrap across several rows or when you want a larger area to click and start typing.
```tsx
import { useState } from "react";
import { TagInput } from "@tilt-legal/cubitt-components/primitives";
const initialTags = [
{ id: "contract-review", label: "Contract Review" },
{ id: "employment", label: "Employment" },
{ id: "urgent", label: "Urgent" },
];
export default function Component() {
const [tags, setTags] = useState(initialTags);
return (
);
}
```
### URL State [#url-state]
```tsx
import { TagInput } from "@tilt-legal/cubitt-components/primitives";
// Synced with ?demo-tags=foo,bar
export default function Component() {
return ;
}
```
## API Reference [#api-reference]
### TagInput [#taginput]
| Prop | Type | Default | Description |
| ---------------------- | --------------------------------------- | --------------------------- | --------------------------------------------- |
| `tags` | `{ id: string; label: string }[]` | — | Controlled tags. |
| `defaultTags` | `{ id: string; label: string }[]` | — | Uncontrolled initial tags. |
| `onTagsChange` | `(next: Tag[]) => void` | — | Change handler for controlled usage. |
| `options` | `{ id: string; label: string }[]` | — | Predefined selectable options. |
| `variant` | `"sm" \| "md" \| "lg"` | `"md"` | Size variant. |
| `placeholder` | `string` | — | Placeholder for the input. |
| `className` | `string` | — | Additional className for the wrapper. |
| `inputProps` | `InputHTMLAttributes` | — | Forward id/name/aria/blur to the inner input. |
| `allowDuplicates` | `boolean` | `false` | Allow duplicate tag labels. |
| `enableExcelPaste` | `boolean` | `true` | Split pasted CSV/TSV/newlines into tags. |
| `enableCommaDelimiter` | `boolean` | `true` | Comma key creates a tag. |
| `pasteDelimiters` | `string[]` | `[",", "\n", "\r\n", "\t"]` | Delimiters used when splitting pasted text. |
#### URL State Props [#url-state-props]
When `paramName` is provided, `TagInput` syncs its tags to a string\[] URL parameter via TanStack Router search params.
| Prop | Type | Default | Description |
| --------------------- | --------------------------------- | ------- | --------------------------------------------------------- |
| `paramName` | `string` | — | URL parameter name to sync. Enables URL state management. |
| `onUrlValueChange` | `(value: string[]\|null) => void` | — | Callback when URL parameter value changes. |
| `paramClearOnDefault` | `boolean` | `true` | Remove URL param when value equals default. |
| `paramThrottle` | `number` | — | Throttle URL updates in milliseconds. |
| `paramDebounce` | `number` | — | Debounce URL updates in milliseconds. |