Ark Logo
GitHub
Components
Tags input

Tags Input

A component that allows users to add tags to an input field.

React
Solid
Vue

Anatomy

To set up the tags input correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the TagsInput component in your project. Let's take a look at the most basic example:

import { TagsInput } from '@ark-ui/react'

export const Basic = () => {
  return (
    <TagsInput.Root>
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label>Frameworks</TagsInput.Label>
            <TagsInput.Control>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value}>
                  <TagsInput.ItemPreview>
                    <TagsInput.ItemText>{value}</TagsInput.ItemText>
                    <TagsInput.ItemDeleteTrigger>Delete</TagsInput.ItemDeleteTrigger>
                  </TagsInput.ItemPreview>
                  <TagsInput.ItemInput />
                </TagsInput.Item>
              ))}
            </TagsInput.Control>
            <TagsInput.Input placeholder="Add Framework" />
            <TagsInput.ClearTrigger>Clear all</TagsInput.ClearTrigger>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}

When the input has an empty value or the caret is at the start position, the tags can be selected by using the arrow left and arrow right keys. When "visual" focus in on any tag:

  • Pressing Enter or double-clicking on the tag will put it in edit mode, allowing the user change its value and press Enter to commit the changes.
  • Pressing Delete or Backspace will delete the tag that has visual focus.

Setting the initial tags

To set the initial tag values, set the defaultValue prop.

Example not found

Limiting the number of tags

To limit the number of tags within the component, you can set the max property to the limit you want. The default value is Infinity.

When the tag reaches the limit, new tags cannot be added except the allowOverflow prop is set to true.

Example not found

Validating Tags

Before a tag is added, the validate function is called to determine whether to accept or reject a tag.

A common use-case for validating tags is preventing duplicates or validating the data type.

import { TagsInput } from '@ark-ui/react'

export const Validated = () => {
  return (
    <TagsInput.Root
      validate={(details) => {
        return !details.value.includes(details.inputValue)
      }}
    >
      <TagsInput.Context>
        {(tagsInput) => (
          <>
            <TagsInput.Label>Frameworks</TagsInput.Label>
            <TagsInput.Control>
              {tagsInput.value.map((value, index) => (
                <TagsInput.Item key={index} index={index} value={value}>
                  <TagsInput.ItemInput />
                  <TagsInput.ItemText>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger>Delete</TagsInput.ItemDeleteTrigger>
                </TagsInput.Item>
              ))}
            </TagsInput.Control>
            <TagsInput.Input placeholder="Add Framework" />
            <TagsInput.ClearTrigger>Clear all</TagsInput.ClearTrigger>
          </>
        )}
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  )
}

Blur behavior

When the tags input is blurred, you can configure the action the component should take by passing the blurBehavior prop.

  • add — Adds the tag to the list of tags.
  • clear — Clears the tags input value.
Example not found

Paste behavior

To add a tag when a arbitrary value is pasted in the input element, pass the addOnPaste prop.

When a value is pasted, the component will:

  • check if the value is a valid tag based on the validate option
  • split the value by the delimiter option passed
Example not found

Disable tag editing

by default the tags can be edited by double-clicking on the tag or focusing on them and pressing Enter. To disable this behavior, pass allowEditTag={false}

Example not found

Events

During the lifetime of the tags input interaction, here's a list of events we emit:

  • onValueChange — invoked when the tag value changes.
  • onHighlightChange — invoked when a tag has visual focus.
  • onValueInvalid — invoked when the max tag count is reached or the validate function returns false.
Example not found

API Reference

Root

PropDefaultType
addOnPaste
boolean

Whether to add a tag when you paste values into the tag input

allowOverflow
boolean

Whether to allow tags to exceed max. In this case, we'll attach `data-invalid` to the root

asChild
boolean

Render as a different element type.

autoFocus
boolean

Whether the input should be auto-focused

blurBehavior'none'
'clear' | 'add'

The behavior of the tags input when the input is blurred - `"add"`: add the input value as a new tag - `"none"`: do nothing - `"clear"`: clear the input value

defaultValue
string[]

The initial value of the tags input when it is first rendered. Use when you do not need to control the state of the tags input.

delimiter','
string | RegExp

The character that serves has: - event key to trigger the addition of a new tag - character used to split tags when pasting into the input

disabled
boolean

Whether the tags input should be disabled

editable
boolean

Whether a tag can be edited after creation. If `true` and focus is on a tag, pressing `Enter`or double clicking will edit the tag.

form
string

The associate form of the underlying input element.

id
string

The unique identifier of the machine.

ids
Partial<{ root: string input: string clearBtn: string label: string control: string item(opts: ItemProps): string itemDeleteTrigger(opts: ItemProps): string itemInput(opts: ItemProps): string }>

The ids of the elements in the tags input. Useful for composition.

inputValue
string

The tag input's value

invalid
boolean

Whether the tags input is invalid

max
number

The max number of tags

maxLength
number

The max length of the input.

name
string

The name attribute for the input. Useful for form submissions

onFocusOutside
(event: FocusOutsideEvent) => void

Function called when the focus is moved outside the component

onHighlightChange
(details: HighlightChangeDetails) => void

Callback fired when a tag is highlighted by pointer or keyboard navigation

onInputValueChange
(details: InputValueChangeDetails) => void

Callback fired when the input value is updated

onInteractOutside
(event: InteractOutsideEvent) => void

Function called when an interaction happens outside the component

onPointerDownOutside
(event: PointerDownOutsideEvent) => void

Function called when the pointer is pressed down outside the component

onValueChange
(details: ValueChangeDetails) => void

Callback fired when the tag values is updated

onValueInvalid
(details: ValidityChangeDetails) => void

Callback fired when the max tag count is reached or the `validateTag` function returns `false`

readOnly
boolean

Whether the tags input should be read-only

translations
IntlTranslations

Specifies the localized strings that identifies the accessibility elements and their states

validate
(details: ValidateArgs) => boolean

Returns a boolean that determines whether a tag can be added. Useful for preventing duplicates or invalid tag values.

value
string[]

The tag values

ClearTrigger

PropDefaultType
asChild
boolean

Render as a different element type.

Control

PropDefaultType
asChild
boolean

Render as a different element type.

HiddenInput

PropDefaultType
asChild
boolean

Render as a different element type.

Input

PropDefaultType
asChild
boolean

Render as a different element type.

ItemDeleteTrigger

PropDefaultType
asChild
boolean

Render as a different element type.

ItemInput

PropDefaultType
asChild
boolean

Render as a different element type.

ItemPreview

PropDefaultType
asChild
boolean

Render as a different element type.

Item

PropDefaultType
index
string | number

value
string

asChild
boolean

Render as a different element type.

disabled
boolean

ItemText

PropDefaultType
asChild
boolean

Render as a different element type.

Label

PropDefaultType
asChild
boolean

Render as a different element type.

Previous

Tabs

Next

Toast