---
title: "Tag Input"
description: "A text field that keeps what was typed as removable chips."
---

Use it for a short, free-form list: tags on a server listing, blocked words, allowed domains. `Enter` or a comma turns the text into a chip, `Backspace` in an empty field takes the last chip back, and a pasted list is split on commas and new lines. A duplicate is dropped.

When the choices come from a known set, use a [Select Menu](/docs/components/select-menu) or an [Entity Select](/docs/components/entity-select) instead.

_Live example of Tag Input — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add tag-input
```

Files written — React: components/ui/tag-input.tsx. Vue: components/ui/tag-input/TagInput.vue, components/ui/tag-input/index.ts.

## Usage

React:

```tsx
import { TagInput } from "@/components/ui/tag-input"
```

Vue:

```ts
import { TagInput } from "@/components/ui/tag-input"
```

## API reference

**`TagInput`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / v-model` | `string[]` | — | The list of tags. In React, leave it undefined and pass `defaultValue` to let the component own it. |
| `onValueChange` | `(value: string[]) => void` | — | React only. Called when a tag is added or removed; Vue emits `update:modelValue`. |
| `max` | `number` | — | Stops accepting tags once the list is this long. |
| `invalid` | `boolean` | `false` | Turns the border to the danger colour and sets `aria-invalid` on the input. |
| `disabled` | `boolean` | `false` | Stops the field and the remove buttons taking input. |
| `removeLabel` | `(tag: string) => string` | `(tag) => `Remove ${tag}`` | Accessible name of a tag's remove button. |

Every other attribute is passed to the text input, so `placeholder`, `id` and `aria-describedby` go where a label expects them. Inside a `Field` marked `invalid`, the border follows the field without the prop.

## Accessibility

The text input is the field a label points at; give it an `id` and a `<label>`, or an `aria-label`. Each chip's remove button is a real button with its own name, reached with `Tab` before the input. Tell the reader how to commit a tag in the helper text, because nothing on screen says that `Enter` does it.

In the HTML flavour, `data-newt-remove-label` on the field names a new chip's remove button. `{tag}` stands for the chip's text. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Tag Input reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
