# Tags Input

URL: https://ark-ui.com/docs/components/tags-input
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/tags-input.mdx

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

---

<ComponentPreview id="TagsInput" />

## Anatomy

<Anatomy id="tags-input" />

```tsx
<TagsInput.Root>
  <TagsInput.Label />
  <TagsInput.Control>
    <TagsInput.Item>
      <TagsInput.ItemPreview>
        <TagsInput.ItemText />
        <TagsInput.ItemDeleteTrigger />
      </TagsInput.ItemPreview>
      <TagsInput.ItemInput />
    </TagsInput.Item>
    <TagsInput.Input />
    <TagsInput.ClearTrigger />
  </TagsInput.Control>
  <TagsInput.HiddenInput />
</TagsInput.Root>
```

## Examples

**Example: basic**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Basic() {
  <TagsInput.Root class={styles.Root}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Controlled

Use the `value` and `onValueChange` props to programmatically control the tags input's state. This allows you to manage
the tags array externally and respond to changes.

**Example: controlled**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tags-input.module.css';

export component Controlled() {
  let value = track<string[]>(['React', 'Solid']);

  <TagsInput.Root
    class={styles.Root}
    {value}
    onValueChange={(details) => {
      @value = details.value;
    }}
  >
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const val of @context.value; index i; key val) {
            <TagsInput.Item class={styles.Item} index={i} value={val}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{val}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Controlled Input Value

Use the `inputValue` and `onInputValueChange` props to control the text input field independently. This is useful for
clearing the input or pre-filling it programmatically.

**Example: controlled-input-value**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import { track } from 'ripple';
import styles from 'styles/tags-input.module.css';
import button from 'styles/button.module.css';

export component ControlledInputValue() {
  let inputValue = track('');

  <div class="stack">
    <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
      <button
        class={button.Root}
        type="button"
        onClick={() => {
          @inputValue = 'React';
        }}
      >
        {'Set to "React"'}
      </button>
      <button
        class={button.Root}
        type="button"
        onClick={() => {
          @inputValue = '';
        }}
      >
        {'Clear Input'}
      </button>
      <span style={{ fontSize: '14px' }}>
        {'Current: "'}
        {@inputValue}
        {'"'}
      </span>
    </div>

    <TagsInput.Root
      class={styles.Root}
      {inputValue}
      onInputValueChange={(details) => {
        @inputValue = details.inputValue;
      }}
    >
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
  </div>
}

```

### Root Provider

An alternative way to control the tags input is to use the `RootProvider` component and the `useTagsInput` hook. This
way you can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { TagsInput, useTagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component RootProvider() {
  const tagsInput = useTagsInput();

  <div class="stack">
    <TagsInput.RootProvider class={styles.Root} value={tagsInput}>
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.RootProvider>

    <output>
      {'values: '}
      {JSON.stringify(@tagsInput.value)}
    </output>
  </div>
}

```

### Field

The `Field` component helps manage form-related state and accessibility attributes of a tags input. It includes handling
ARIA labels, helper text, and error text to ensure proper accessibility.

**Example: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import field from 'styles/field.module.css';
import styles from 'styles/tags-input.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <TagsInput.Root class={styles.Root}>
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Max 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: max-with-overflow**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component MaxWithOverflow() {
  <TagsInput.Root class={styles.Root} max={3} allowOverflow>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Custom Delimiter

Use the `delimiter` prop with a regex pattern to specify multiple characters that can separate tags. By default, only
the Enter key creates tags.

**Example: delimiter**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

const DELIMITER_PATTERN = /[,;\s]/;

export component Delimiter() {
  <TagsInput.Root class={styles.Root} delimiter={DELIMITER_PATTERN}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>
          {'Frameworks (add with comma, semicolon, or space)'}
        </TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add tag" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Disabled

Use the `disabled` prop to make the tags input non-interactive. Users won't be able to add, remove, or edit tags.

**Example: disabled**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Disabled() {
  <TagsInput.Root class={styles.Root} defaultValue={['React', 'Solid', 'Vue']} disabled>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Invalid

Use the `invalid` prop to mark the tags input as invalid for form validation purposes.

**Example: invalid**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Invalid() {
  <TagsInput.Root class={styles.Root} invalid>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Max Length

Use the `maxLength` prop to limit the number of characters allowed per tag. This prevents users from creating overly
long tags.

**Example: max-tag-length**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component MaxTagLength() {
  <TagsInput.Root class={styles.Root} maxLength={10}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks (Max 10 characters)'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Read-only

Use the `readOnly` prop to make tags visible but not editable. Users can view tags but cannot add, remove, or modify
them.

**Example: readonly**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component Readonly() {
  <TagsInput.Root class={styles.Root} defaultValue={['React', 'Solid', 'Vue']} readOnly>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Validation

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.

**Example: validation**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

const TAG_PATTERN = /^[a-zA-Z0-9-]+$/;

const validateTag = ({
  value,
  inputValue,
}: {
  value: string[];
  inputValue: string;
}) => !!inputValue?.trim() && !value.includes(inputValue) && inputValue.length >= 3 &&
  TAG_PATTERN.test(inputValue);

export component Validation() {
  <TagsInput.Root class={styles.Root} validate={validateTag}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>
          {'Frameworks (Min 3 chars, alphanumeric)'}
        </TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </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: blur-behavior**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component BlurBehavior() {
  <TagsInput.Root class={styles.Root} blurBehavior="add">
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### 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: paste-behavior**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component PasteBehavior() {
  <TagsInput.Root class={styles.Root} addOnPaste delimiter=",">
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Disable Editing

by default the tags can be edited by double-clicking on the tag or focusing on them and pressing

<kbd>Enter</kbd>. To disable this behavior, pass `editable={false}`

**Example: disabled-editing**

```ripple
import { TagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';

export component DisabledEditing() {
  <TagsInput.Root class={styles.Root} editable={false}>
    <TagsInput.Context>
      component children({ context }) {
        <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
        <TagsInput.Control class={styles.Control}>
          for (const value of @context.value; index i; key value) {
            <TagsInput.Item class={styles.Item} index={i} {value}>
              <TagsInput.ItemPreview class={styles.ItemPreview}>
                <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                  <X />
                </TagsInput.ItemDeleteTrigger>
              </TagsInput.ItemPreview>
              <TagsInput.ItemInput class={styles.ItemInput} />
            </TagsInput.Item>
          }
          <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
          <TagsInput.ClearTrigger class={styles.ClearTrigger}>
            <X />
          </TagsInput.ClearTrigger>
        </TagsInput.Control>
      }
    </TagsInput.Context>
    <TagsInput.HiddenInput />
  </TagsInput.Root>
}

```

### Programmatic Control

Use the `useTagsInput` hook with `RootProvider` to access the component's API methods like `addValue()`, `setValue()`,
and `clearValue()` for full programmatic control.

**Example: programmatic-control**

```ripple
import { TagsInput, useTagsInput } from 'ark-ripple/tags-input';
import { X } from 'lucide-ripple';
import styles from 'styles/tags-input.module.css';
import button from 'styles/button.module.css';

export component ProgrammaticControl() {
  const tagsInput = useTagsInput();

  <div class="stack">
    <div style={{ display: 'flex', gap: '8px' }}>
      <button class={button.Root} type="button" onClick={() => @tagsInput.addValue('React')}>
        {'Add React'}
      </button>
      <button class={button.Root} type="button" onClick={() => @tagsInput.addValue('Solid')}>
        {'Add Solid'}
      </button>
      <button
        class={button.Root}
        type="button"
        onClick={() => @tagsInput.setValue(['Vue', 'Svelte'])}
      >
        {'Set to Vue & Svelte'}
      </button>
      <button class={button.Root} type="button" onClick={() => @tagsInput.clearValue()}>
        {'Clear All'}
      </button>
    </div>

    <TagsInput.RootProvider class={styles.Root} value={tagsInput}>
      <TagsInput.Context>
        component children({ context }) {
          <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
          <TagsInput.Control class={styles.Control}>
            for (const value of @context.value; index i; key value) {
              <TagsInput.Item class={styles.Item} index={i} {value}>
                <TagsInput.ItemPreview class={styles.ItemPreview}>
                  <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
                  <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                    <X />
                  </TagsInput.ItemDeleteTrigger>
                </TagsInput.ItemPreview>
                <TagsInput.ItemInput class={styles.ItemInput} />
              </TagsInput.Item>
            }
            <TagsInput.Input placeholder="Add Framework" class={styles.Input} />
            <TagsInput.ClearTrigger class={styles.ClearTrigger}>
              <X />
            </TagsInput.ClearTrigger>
          </TagsInput.Control>
        }
      </TagsInput.Context>
      <TagsInput.HiddenInput />
    </TagsInput.RootProvider>
  </div>
}

```

### Combobox

Combine TagsInput with Combobox to create an autocomplete tags input. This pattern uses shared IDs between both
components and the `asChild` prop to compose the inputs together.

**Example: with-combobox**

```ripple
import { Combobox, useCombobox, useListCollection } from 'ark-ripple/combobox';
import { useFilter } from 'ark-ripple/locale';
import { Portal } from 'ark-ripple/portal';
import { TagsInput, useTagsInput } from 'ark-ripple/tags-input';
import { Check, X } from 'lucide-ripple';
import combobox from 'styles/combobox.module.css';
import styles from 'styles/tags-input.module.css';

export component WithCombobox() {
  const filterApi = useFilter({ sensitivity: 'base' });

  const { collection, filter } = useListCollection(
    {
      initialItems: [
        'React',
        'Solid',
        'Vue',
        'Svelte',
        'Angular',
        'Preact',
        'Next.js',
        'Astro',
        'Nuxt',
      ],
      filter: @filterApi.contains,
    },
  );

  const sharedId = 'tags-combobox-1';

  const tagsInput = useTagsInput(
    {
      ids: { input: `input_${sharedId}`, control: `control_${sharedId}` },
    },
  );

  const comboboxApi = useCombobox(
    {
      ids: { input: `input_${sharedId}`, control: `control_${sharedId}` },
      collection,
      onInputValueChange(details) {
        filter(details.inputValue);
      },
      value: [],
      allowCustomValue: true,
      onValueChange: (details) => {
        if (details.value[0]) {
          @tagsInput.addValue(details.value[0]);
        }
      },
      selectionBehavior: 'clear',
    },
  );

  <Combobox.RootProvider value={comboboxApi}>
    <TagsInput.RootProvider class={styles.Root} value={tagsInput}>
      <TagsInput.Label class={styles.Label}>{'Frameworks'}</TagsInput.Label>
      <TagsInput.Control class={styles.Control}>
        for (const value of @tagsInput.value; index i; key value) {
          <TagsInput.Item class={styles.Item} index={i} {value}>
            <TagsInput.ItemPreview class={styles.ItemPreview}>
              <TagsInput.ItemText class={styles.ItemText}>{value}</TagsInput.ItemText>
              <TagsInput.ItemDeleteTrigger class={styles.ItemDeleteTrigger}>
                <X />
              </TagsInput.ItemDeleteTrigger>
            </TagsInput.ItemPreview>
            <TagsInput.ItemInput class={styles.ItemInput} />
          </TagsInput.Item>
        }
        <Combobox.Input>
          component asChild({ propsFn }) {
            <TagsInput.Input {...propsFn({ placeholder: 'Add Framework', class: styles.Input })} />
          }
        </Combobox.Input>
        <TagsInput.ClearTrigger class={styles.ClearTrigger}>
          <X />
        </TagsInput.ClearTrigger>
      </TagsInput.Control>
      <TagsInput.HiddenInput />
    </TagsInput.RootProvider>

    <Portal>
      <Combobox.Positioner>
        <Combobox.Content class={combobox.Content}>
          <Combobox.Empty class={combobox.Item}>{'No frameworks found'}</Combobox.Empty>
          for (const item of @collection.items; key item) {
            <Combobox.Item class={combobox.Item} {item}>
              <Combobox.ItemText class={combobox.ItemText}>{item}</Combobox.ItemText>
              <Combobox.ItemIndicator class={combobox.ItemIndicator}>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          }
        </Combobox.Content>
      </Combobox.Positioner>
    </Portal>
  </Combobox.RootProvider>
}

```

## Guides

### Navigation

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 <kbd>Enter</kbd> or double-clicking on the tag will put it in edit mode, allowing the user change its value
  and press <kbd>Enter</kbd> to commit the changes.
- Pressing <kbd>Delete</kbd> or <kbd>Backspace</kbd> will delete the tag that has _visual_ focus.

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `addOnPaste` | `boolean` | No | Whether to add a tag when you paste values into the tag input |
| `allowOverflow` | `boolean` | No | Whether to allow tags to exceed max. In this case,
we'll attach `data-invalid` to the root |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `autoFocus` | `boolean` | No | Whether the input should be auto-focused |
| `blurBehavior` | `'clear' | 'add'` | No | 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` | No | The initial tag input value when rendered.
Use when you don't need to control the tag input value. |
| `defaultValue` | `string[]` | No | The initial tag value when rendered.
Use when you don't need to control the tag value. |
| `delimiter` | `string | RegExp` | No | 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` | No | Whether the tags input should be disabled |
| `editable` | `boolean` | No | Whether a tag can be edited after creation, by pressing `Enter` or double clicking. |
| `form` | `string` | No | The associate form of the underlying input element. |
| `id` | `string` | No | 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
}>` | No | The ids of the elements in the tags input. Useful for composition. |
| `inputValue` | `string` | No | The controlled tag input's value |
| `invalid` | `boolean` | No | Whether the tags input is invalid |
| `max` | `number` | No | The max number of tags |
| `maxLength` | `number` | No | The max length of the input. |
| `name` | `string` | No | The name attribute for the input. Useful for form submissions |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onHighlightChange` | `(details: HighlightChangeDetails) => void` | No | Callback fired when a tag is highlighted by pointer or keyboard navigation |
| `onInputValueChange` | `(details: InputValueChangeDetails) => void` | No | Callback fired when the input value is updated |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback fired when the tag values is updated |
| `onValueInvalid` | `(details: ValidityChangeDetails) => void` | No | Callback fired when the max tag count is reached or the `validateTag` function returns `false` |
| `placeholder` | `string` | No | The placeholder text for the input |
| `readOnly` | `boolean` | No | Whether the tags input should be read-only |
| `required` | `boolean` | No | Whether the tags input is required |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `validate` | `(details: ValidateArgs) => boolean` | No | Returns a boolean that determines whether a tag can be added.
Useful for preventing duplicates or invalid tag values. |
| `value` | `string[]` | No | The controlled tag value |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | root |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled |
| `[data-focus]` | Present when focused |
| `[data-empty]` | Present when the content is empty |


**ClearTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ClearTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | clear-trigger |
| `[data-readonly]` | Present when read-only |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | control |
| `[data-disabled]` | Present when disabled |
| `[data-readonly]` | Present when read-only |
| `[data-invalid]` | Present when invalid |
| `[data-focus]` | Present when focused |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Input Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | input |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-empty]` | Present when the content is empty |


**ItemDeleteTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemDeleteTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-delete-trigger |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**ItemInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemPreview Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemPreview Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-preview |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `string | number` | Yes |  |
| `value` | `string` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item |
| `[data-value]` | The value of the item |
| `[data-disabled]` | Present when disabled |


**ItemText Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**ItemText Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | item-text |
| `[data-disabled]` | Present when disabled |
| `[data-highlighted]` | Present when highlighted |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tags-input |
| `[data-part]` | label |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]` | Present when invalid |
| `[data-readonly]` | Present when read-only |
| `[data-required]` | Present when required |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTagsInputReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `empty` | `boolean` | Whether the tags are empty |
| `inputValue` | `string` | The value of the tags entry input. |
| `value` | `string[]` | The value of the tags as an array of strings. |
| `valueAsString` | `string` | The value of the tags as a string. |
| `count` | `number` | The number of the tags. |
| `atMax` | `boolean` | Whether the tags have reached the max limit. |
| `setValue` | `(value: string[]) => void` | Function to set the value of the tags. |
| `clearValue` | `(id?: string) => void` | Function to clear the value of the tags. |
| `addValue` | `(value: string) => void` | Function to add a tag to the tags. |
| `setValueAtIndex` | `(index: number, value: string) => void` | Function to set the value of a tag at the given index. |
| `setInputValue` | `(value: string) => void` | Function to set the value of the tags entry input. |
| `clearInputValue` | `VoidFunction` | Function to clear the value of the tags entry input. |
| `focus` | `VoidFunction` | Function to focus the tags entry input. |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of a tag |


## Accessibility

### Keyboard Support

<KeyBindingsTable id="tags-input" />