Skip to content

ComponentsForms & data

SourceSource

Tag Input

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 or an Entity Select instead.

Root class newt-tag-input
"use client"

import * as React from "react"

import { Field, FieldHelp, Label } from "@/registry/bases/newt/ui/form-fields"
import { TagInput } from "@/registry/bases/newt/ui/tag-input"

export default function TagInputDemo() {
  const [tags, setTags] = React.useState<readonly string[]>([
    "moderation",
    "music",
  ])

  return (
    <Field className="w-full max-w-sm">
      <Label htmlFor="newt-tag-input-example">Server tags</Label>
      <TagInput
        id="newt-tag-input-example"
        placeholder="Add a tag"
        max={5}
        value={tags}
        onValueChange={setTags}
      />
      <FieldHelp>
        {tags.length} of 5. Press Enter or a comma to add one.
      </FieldHelp>
    </Field>
  )
}
<script setup lang="ts">
import { ref } from "vue"
import { Field, FieldHelp, Label } from "~~/registry/bases/newt/ui/form-fields"
import { TagInput } from "~~/registry/bases/newt/ui/tag-input"

const tags = ref<readonly string[]>(["moderation", "music"])
</script>

<template>
  <Field class="w-full max-w-sm">
    <Label for="newt-tag-input-example">Server tags</Label>
    <TagInput
      id="newt-tag-input-example"
      v-model="tags"
      placeholder="Add a tag"
      :max="5"
    />
    <FieldHelp>
      {{ tags.length }} of 5. Press Enter or a comma to add one.
    </FieldHelp>
  </Field>
</template>

Installation

npx newtui@latest add tag-inputnpx shadcn@latest add @newtui/tag-inputnpx shadcn-vue@latest add @newtui/tag-inputpnpm dlx newtui@latest add tag-inputpnpm dlx shadcn@latest add @newtui/tag-inputpnpm dlx shadcn-vue@latest add @newtui/tag-inputyarn dlx newtui@latest add tag-inputyarn dlx shadcn@latest add @newtui/tag-inputyarn dlx shadcn-vue@latest add @newtui/tag-inputbunx newtui@latest add tag-inputbunx shadcn@latest add @newtui/tag-inputbunx shadcn-vue@latest add @newtui/tag-inputdeno run -A npm:newtui@latest add tag-inputdeno run -A npm:shadcn@latest add @newtui/tag-inputdeno run -A npm:shadcn-vue@latest add @newtui/tag-inputvlx newtui@latest add tag-inputvlx shadcn@latest add @newtui/tag-inputvlx shadcn-vue@latest add @newtui/tag-inputvp dlx newtui@latest add tag-inputvp dlx shadcn@latest add @newtui/tag-inputvp dlx shadcn-vue@latest add @newtui/tag-inputnubx newtui@latest add tag-inputnubx shadcn@latest add @newtui/tag-inputnubx shadcn-vue@latest add @newtui/tag-inputnlx newtui@latest add tag-inputnlx shadcn@latest add @newtui/tag-inputnlx shadcn-vue@latest add @newtui/tag-inputupx newtui@latest add tag-inputupx shadcn@latest add @newtui/tag-inputupx shadcn-vue@latest add @newtui/tag-input

The shadcn CLI needs the @newtui registry in your components.json. Set it up.

Copy the source into your project

"use client"

import * as React from "react"

import { cn } from "@/lib/utils"

export interface TagInputProps extends Omit<
  React.InputHTMLAttributes<HTMLInputElement>,
  "value" | "defaultValue" | "onChange" | "type"
> {
  /** Controlled list. Leave undefined to let the component own it. */
  value?: readonly string[]
  defaultValue?: readonly string[]
  onValueChange?: (value: readonly string[]) => void
  /** Stop accepting tags once the list is this long. */
  max?: number
  invalid?: boolean
  /** The accessible name of a tag's remove button. */
  removeLabel?: (tag: string) => string
}

const defaultRemoveLabel = (tag: string) => `Remove ${tag}`

/*
 * A text field that keeps what was typed as chips. Enter or a comma commits
 * the text, 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
 * rather than added twice.
 */
const TagInput = React.forwardRef<HTMLInputElement, TagInputProps>(
  (
    {
      className,
      value,
      defaultValue = [],
      onValueChange,
      max,
      invalid = false,
      disabled = false,
      removeLabel = defaultRemoveLabel,
      onKeyDown,
      onPaste,
      ...props
    },
    ref
  ) => {
    const [internal, setInternal] =
      React.useState<readonly string[]>(defaultValue)
    const [text, setText] = React.useState("")
    const isControlled = value !== undefined
    const tags = isControlled ? value : internal

    const commit = (next: readonly string[]) => {
      if (!isControlled) setInternal(next)
      onValueChange?.(next)
    }

    const add = (candidates: readonly string[]) => {
      const next = [...tags]
      for (const candidate of candidates) {
        const tag = candidate.trim()
        if (tag === "" || next.includes(tag)) continue
        if (max !== undefined && next.length >= max) break
        next.push(tag)
      }
      if (next.length !== tags.length) commit(next)
    }

    return (
      // The wrapper is drawn as the field; a click anywhere in it is a click
      // on the input, which is the only thing in it a keyboard reaches first.
      // oxlint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions -- pointer convenience only; the input and the remove buttons are the keyboard targets
      <div
        data-tag-input=""
        data-invalid={invalid || undefined}
        onClick={(event) => {
          if (event.target === event.currentTarget) {
            event.currentTarget.querySelector("input")?.focus()
          }
        }}
        className={cn(
          "flex min-h-[42px] w-full cursor-text flex-wrap items-center gap-1.5 rounded-[var(--newt-radius-sm)] border border-newt-border bg-newt-bg-input px-2 py-1.5 transition-colors duration-fast ease-newt focus-within:border-newt-brand data-[invalid]:border-newt-danger group-data-[invalid]/field:border-newt-danger",
          disabled && "cursor-not-allowed opacity-50",
          className
        )}
      >
        {tags.map((tag) => (
          <span
            key={tag}
            className="inline-flex max-w-full items-center gap-1 rounded-[var(--newt-radius-sm)] bg-newt-bg-active py-[3px] pe-1 ps-2 text-[13px] font-medium leading-[18px] text-newt-text-primary"
          >
            <span className="truncate">{tag}</span>
            <button
              type="button"
              disabled={disabled}
              aria-label={removeLabel(tag)}
              onClick={(event) => {
                commit(tags.filter((each) => each !== tag))
                event.currentTarget
                  .closest("[data-tag-input]")
                  ?.querySelector("input")
                  ?.focus()
              }}
              className="inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-full text-newt-text-muted hover:bg-newt-danger hover:text-newt-on-accent focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-newt-text-link"
            >
              <svg viewBox="0 0 16 16" aria-hidden="true" className="h-3 w-3">
                <path
                  fill="currentColor"
                  d="M4.3 4.3a1 1 0 0 1 1.4 0L8 6.6l2.3-2.3a1 1 0 1 1 1.4 1.4L9.4 8l2.3 2.3a1 1 0 0 1-1.4 1.4L8 9.4l-2.3 2.3a1 1 0 0 1-1.4-1.4L6.6 8 4.3 5.7a1 1 0 0 1 0-1.4Z"
                />
              </svg>
            </button>
          </span>
        ))}
        <input
          ref={ref}
          type="text"
          value={text}
          disabled={disabled}
          aria-invalid={invalid || undefined}
          onChange={(event) => setText(event.target.value)}
          onKeyDown={(event) => {
            onKeyDown?.(event)
            /*
             * While an input method is composing, Enter confirms a candidate
             * and is not the reader committing a tag.
             */
            if (event.defaultPrevented || event.nativeEvent.isComposing) return
            if (event.key === "Enter" || event.key === ",") {
              event.preventDefault()
              add([text])
              setText("")
            } else if (
              event.key === "Backspace" &&
              text === "" &&
              tags.length > 0
            ) {
              commit(tags.slice(0, -1))
            }
          }}
          onPaste={(event) => {
            onPaste?.(event)
            if (event.defaultPrevented) return
            const pasted = event.clipboardData.getData("text")
            if (!/[,\n]/.test(pasted)) return
            event.preventDefault()
            add(pasted.split(/[,\n]/))
          }}
          className="min-w-20 flex-1 border-0 bg-transparent px-1 py-[3px] font-[family-name:var(--newt-font-sans)] text-sm leading-[18px] text-newt-text-primary placeholder:text-newt-text-muted focus:outline-none disabled:cursor-not-allowed"
          {...props}
        />
      </div>
    )
  }
)
TagInput.displayName = "TagInput"

export { TagInput }
<script setup lang="ts">
import { ref, type HTMLAttributes } from "vue"

import { cn } from "@/lib/utils"

/*
 * A text field that keeps what was typed as chips. Enter or a comma commits
 * the text, 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
 * rather than added twice. Attributes other than `class` land on the input.
 */
defineOptions({ inheritAttrs: false })

const props = withDefaults(
  defineProps<{
    class?: HTMLAttributes["class"]
    /** Stop accepting tags once the list is this long. */
    max?: number
    invalid?: boolean
    disabled?: boolean
    /** The accessible name of a tag's remove button. */
    removeLabel?: (tag: string) => string
  }>(),
  {
    invalid: false,
    disabled: false,
    removeLabel: (tag: string) => `Remove ${tag}`,
  }
)

const tags = defineModel<readonly string[]>({ default: () => [] })

const text = ref("")
const inner = ref<HTMLInputElement | null>(null)

function add(candidates: readonly string[]) {
  const next = [...tags.value]
  for (const candidate of candidates) {
    const tag = candidate.trim()
    if (tag === "" || next.includes(tag)) continue
    if (props.max !== undefined && next.length >= props.max) break
    next.push(tag)
  }
  if (next.length !== tags.value.length) tags.value = next
}

function remove(tag: string) {
  tags.value = tags.value.filter((each) => each !== tag)
  inner.value?.focus()
}

function onKeydown(event: KeyboardEvent) {
  /*
   * While an input method is composing, Enter confirms a candidate and is not
   * the reader committing a tag.
   */
  if (event.isComposing) return
  if (event.key === "Enter" || event.key === ",") {
    event.preventDefault()
    add([text.value])
    text.value = ""
  } else if (
    event.key === "Backspace" &&
    text.value === "" &&
    tags.value.length > 0
  ) {
    tags.value = tags.value.slice(0, -1)
  }
}

function onPaste(event: ClipboardEvent) {
  const pasted = event.clipboardData?.getData("text") ?? ""
  if (!/[,\n]/.test(pasted)) return
  event.preventDefault()
  add(pasted.split(/[,\n]/))
}

function onWrapperClick(event: MouseEvent) {
  if (event.target === event.currentTarget) inner.value?.focus()
}
</script>

<template>
  <!--
    The wrapper is drawn as the field; a click anywhere in it is a click on
    the input, which is the only thing in it a keyboard reaches first.
  -->
  <div
    :data-invalid="props.invalid ? true : undefined"
    :class="
      cn(
        'flex min-h-[42px] w-full cursor-text flex-wrap items-center gap-1.5 rounded-[var(--newt-radius-sm)] border border-newt-border bg-newt-bg-input px-2 py-1.5 transition-colors duration-fast ease-newt focus-within:border-newt-brand data-[invalid]:border-newt-danger group-data-[invalid]/field:border-newt-danger',
        props.disabled && 'cursor-not-allowed opacity-50',
        props.class
      )
    "
    @click="onWrapperClick"
  >
    <span
      v-for="tag in tags"
      :key="tag"
      class="inline-flex max-w-full items-center gap-1 rounded-[var(--newt-radius-sm)] bg-newt-bg-active py-[3px] pe-1 ps-2 text-[13px] font-medium leading-[18px] text-newt-text-primary"
    >
      <span class="truncate">{{ tag }}</span>
      <button
        type="button"
        :disabled="props.disabled"
        :aria-label="props.removeLabel(tag)"
        class="inline-flex h-4 w-4 shrink-0 items-center justify-center rounded-full text-newt-text-muted hover:bg-newt-danger hover:text-newt-on-accent focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-newt-text-link"
        @click="remove(tag)"
      >
        <svg viewBox="0 0 16 16" aria-hidden="true" class="h-3 w-3">
          <path
            fill="currentColor"
            d="M4.3 4.3a1 1 0 0 1 1.4 0L8 6.6l2.3-2.3a1 1 0 1 1 1.4 1.4L9.4 8l2.3 2.3a1 1 0 0 1-1.4 1.4L8 9.4l-2.3 2.3a1 1 0 0 1-1.4-1.4L6.6 8 4.3 5.7a1 1 0 0 1 0-1.4Z"
          />
        </svg>
      </button>
    </span>
    <input
      v-bind="$attrs"
      ref="inner"
      v-model="text"
      type="text"
      :disabled="props.disabled"
      :aria-invalid="props.invalid ? true : undefined"
      class="min-w-20 flex-1 border-0 bg-transparent px-1 py-[3px] font-[family-name:var(--newt-font-sans)] text-sm leading-[18px] text-newt-text-primary placeholder:text-newt-text-muted focus:outline-none disabled:cursor-not-allowed"
      @keydown="onKeydown"
      @paste="onPaste"
    />
  </div>
</template>
export { default as TagInput } from "./TagInput.vue"

Update the import paths

The files import @/lib/utils and sibling components through the aliases in your components.json. Point them at wherever those live in your project.

No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Tag Input to your React project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.

No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Tag Input to your Vue project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.

Usage

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

export function Example() {
  return <TagInput />
}
<script setup lang="ts">
import { TagInput } from "@/components/ui/tag-input"
</script>

<template>
  <TagInput />
</template>

API reference

TagInput

PropType
value / v-model?string[]

The list of tags. In React, leave it undefined and pass `defaultValue` to let the component own it.

Typestring[]
onValueChange?(value: string[]) => void

React only. Called when a tag is added or removed; Vue emits `update:modelValue`.

Type(value: string[]) => void
max?number

Stops accepting tags once the list is this long.

Typenumber
invalid?boolean

Turns the border to the danger colour and sets `aria-invalid` on the input.

Typeboolean
Defaultfalse
disabled?boolean

Stops the field and the remove buttons taking input.

Typeboolean
Defaultfalse
removeLabel?(tag: string) => string

Accessible name of a tag's remove button.

Type(tag: string) => string
Default(tag) => `Remove ${tag}`

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 lists every English default.

Tokens

Tag Input reads its colours, radii and motion from the --newt-* tokens installed with the library. Override a token and every component that reads it follows, including this one — see the token layer. In the plain HTML and CSS distribution the same component is newt-tag-input.

  • --newt-border
  • --newt-radius-sm
  • --newt-bg-input
  • --newt-duration-fast
  • --newt-ease
  • --newt-brand
  • --newt-bg-active
  • --newt-text-primary
  • --newt-radius-full
  • --newt-text-muted
  • --newt-danger
  • --newt-on-accent
  • --newt-text-link
  • --newt-font-sans