Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsShowcaseBlogGuides
Sponsor

Tags Input

Used to enter multiple values as tags with features like tag creation, deletion, and keyboard navigation.

SourceStorybookRecipeArk
AI TipWant to skip the docs? Use the MCP Server
React
Chakra
TypeScript
Press Enter or Return to add tag

Usage

import { TagsInput } from "@chakra-ui/react"
<TagsInput.Root>
  <TagsInput.Label />
  <TagsInput.Control>
    <TagsInput.Item>
      <TagsInput.ItemPreview>
        <TagsInput.ItemText />
        <TagsInput.ItemDeleteTrigger />
      </TagsInput.ItemPreview>
      <TagsInput.ItemInput />
    </TagsInput.Item>
    <TagsInput.Input />
  </TagsInput.Control>
</TagsInput.Root>

Shortcuts

The TagsInput component also provides a set of shortcuts for common use cases.

TagsInputItems

The TagsInputItems shortcut renders all tag items automatically based on the current value.

This works:

<TagsInput.Context>
  {({ value }) =>
    value.map((tag, index) => (
      <TagsInput.Item key={index} index={index} value={tag}>
        <TagsInput.ItemPreview>
          <TagsInput.ItemText>{tag}</TagsInput.ItemText>
          <TagsInput.ItemDeleteTrigger />
        </TagsInput.ItemPreview>
        <TagsInput.ItemInput />
      </TagsInput.Item>
    ))
  }
</TagsInput.Context>

This might be more concise, if you don't need to customize the items:

<TagsInput.Items />

Examples

Sizes

Use the size prop to adjust the size of the tags input.

React
Chakra
TypeScript
Press Enter or Return to add tag
React
Chakra
TypeScript
Press Enter or Return to add tag
React
Chakra
TypeScript
Press Enter or Return to add tag
React
Chakra
TypeScript
Press Enter or Return to add tag

Variants

Use the variant prop to change the visual style of the tags input.

React
Chakra
TypeScript
Press Enter or Return to add tag
React
Chakra
TypeScript
Press Enter or Return to add tag
React
Chakra
TypeScript
Press Enter or Return to add tag

Controlled

Use the value and onValueChange props to programmatically control the tags.

React
Chakra

Store

An alternative way to control the tags input is to use the RootProvider component and the useTagsInput store hook.

This way you can access the tags input state and methods from outside the component.

Use RootProvider + useTagsInput or Root, not both.

Max Tags

Pass the max prop to the TagsInput.Root component to limit the number of tags that can be added.

sage@company.com
You've invited 1 / 3 guests to your event

Editable Tags

Use the editable prop to enable inline editing of existing tags by clicking on them, allowing users to quickly update tag values.

React
Chakra
Use the arrow keys to navigate and press Enter to edit

Validate Tag

Use the validate prop to implement custom validation rules. Tags will be added when the validation passes.

React
Chakra

Disabled

Use the disabled prop to disable the tags input to prevent user interaction.

React
Chakra

Readonly

Use the readOnly prop to make the tags input read-only. Tags input can be focused but can't be modified.

React
Chakra

Invalid

Pass the invalid prop to the TagsInput.Root component to display the tags input in an invalid state with error messages.

React
Chakra
This is an error

Field

Here's an example that composes the TagsInput.Root with the Field component to add labels, helper text, and error messages.

React
Chakra
TypeScript
Add emails separated by commas

Form

Here's an example that composes the TagsInput.Root with a form to collect structured data and handle submissions.

Add frameworks and libraries you use

Paste

Pass the addOnPaste prop to the TagsInput.Root component to allow users to paste multiple values at once, automatically splitting them into individual tags based on a delimiter.

Copy Tags
React,Chakra,TypeScript

Blur Behavior

Use the blurBehavior prop to configure how the input behaves when it loses focus, such as automatically creating a tag from the current input value.

Custom Delimiter

Use the delimiter prop to use custom delimiters like commas, semicolons, or spaces to create new tags as users type.

Colors

Here's an example that assigns rather color scheme to the tags based on the tag value.

React
Chakra
TypeScript

Combobox

Here's an example that composes the TagsInput component with the Combobox component to create a tags input that allows users to select from a list of predefined tags.

Props

Root

PropDefaultType
addOnPaste false
boolean

Whether to add a tag when you paste values into the tag 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

editable true
boolean

Whether a tag can be edited after creation, by pressing `Enter` or double clicking.

max Infinity
number

The max number of tags

colorPalette gray
'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'cyan' | 'purple' | 'pink'

The color palette of the component

size md
'xs' | 'sm' | 'md' | 'lg'

The size of the component

variant outline
'outline' | 'subtle' | 'flushed'

The variant of the component

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

allowOverflow
boolean

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

autoFocus
boolean

Whether the input should be auto-focused

blurBehavior
'clear' | 'add'

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

defaultInputValue
string

The initial tag input value when rendered. Use when you don't need to control the tag input value.

defaultValue
string[]

The initial tag value when rendered. Use when you don't need to control the tag value.

disabled
boolean

Whether the tags input should be disabled

form
string

The associate form of the underlying input element.

id
string

The unique identifier of the machine.

ids
Partial<{ root: string input: string hiddenInput: 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 controlled tag input's value

invalid
boolean

Whether the tags input is invalid

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

required
boolean

Whether the tags input is required

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 controlled tag value

Item

PropDefaultType
index *
string | number

value *
string

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
disabled
boolean

Explorer

Explore the TagsInput component parts interactively. Click on parts in the sidebar to highlight them in the preview.

React
Chakra

Component Anatomy

Hover to highlight, click to select parts

root

label

control

input

clearTrigger

item

itemPreview

itemInput

itemText

itemDeleteTrigger

tags-input.recipe.ts

Previous

Textarea

Next

Combobox