TagsInput

Free-form chip entry — Enter or comma commits the current token; Backspace on empty removes the last tag.

stable
since v0.1.0
2.58 kB
forms
input

Preview

tsx

import { TagsInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '360px' }}>
      <TagsInput aria-label="Topics" defaultValue={['design', 'systems']} placeholder="Add tag…" />
    </div>
  );
}

Sizes

Three sizes are available: sm, md (default), and lg.

Preview

Open

tsx

import { TagsInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', width: '360px' }}>
      <TagsInput aria-label="Small" size="sm" defaultValue={['alpha', 'beta']} />
      <TagsInput aria-label="Medium" size="md" defaultValue={['alpha', 'beta']} />
      <TagsInput aria-label="Large" size="lg" defaultValue={['alpha', 'beta']} />
    </div>
  );
}

Max tags

Set maxTags to cap how many tags can be added.

Preview

Open

tsx

import { TagsInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '360px' }}>
      <TagsInput aria-label="Up to 3 tags" maxTags={3} placeholder="Add up to 3" />
    </div>
  );
}

Commit keys

Override commitKeys to change which keys commit the current token. Defaults to Enter and ,.

Preview

Open

tsx

import { TagsInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '360px' }}>
      <TagsInput
        aria-label="Tags (Space or Enter to commit)"
        commitKeys={['Enter', ' ']}
        placeholder="Type and press Space"
      />
    </div>
  );
}

Suggestions

Pass suggestions to expose a <datalist> of pre-filled options to the input.

Preview

Open

tsx

import { TagsInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '360px' }}>
      <TagsInput
        aria-label="Languages"
        suggestions={['TypeScript', 'Rust', 'Go', 'Python', 'Elixir']}
        placeholder="Type to see suggestions"
      />
    </div>
  );
}

States

Preview

Open

tsx

import { TagsInput } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', width: '360px' }}>
      <TagsInput aria-label="Default" defaultValue={['one', 'two']} />
      <TagsInput aria-label="Invalid" defaultValue={['one']} invalid />
      <TagsInput aria-label="Read-only" defaultValue={['locked', 'fixed']} readOnly />
      <TagsInput aria-label="Disabled" defaultValue={['disabled']} disabled />
    </div>
  );
}

API

PropTypeDefaultDescription

value

readonly string[]

—

Controlled list of tags.

defaultValue

readonly string[]

—

Uncontrolled initial list of tags.

onValueChange

((tags: string[]) => void)

—

Fires with the next array on every commit / remove.

commitKeys

readonly string[]

["Enter", ","]

Keys that commit the current draft token.

placeholder

string

"Add tag…"

Placeholder rendered when no tags are present.

size

"sm"|"md"|"lg"

"md"

Control size.

variant

"outline"|"filled"|"ghost"

"outline"

Visual treatment.

disabled

boolean

—

Disables interaction.

readOnly

boolean

—

Renders tags but blocks editing.

invalid

boolean

—

Renders the invalid state.

suggestions

readonly string[]

—

Optional suggestions rendered as a `<datalist>` for the inline input.

unique

boolean

true

Disallow duplicate tags (case-sensitive).

maxTags

number

—

Hard cap on tag count.

renderTag

((tag: string, index: number, remove: () => void) => ReactNode)

—

Custom renderer for each tag. Receives the tag string, its index, and a `remove` callback.

label

string

—

Accessible label for the inline input.

aria-label

string

—

string

—

name

string

—

className

string

—

style

CSSProperties

—

Accessibility

Each rendered tag has a remove button with the accessible name Remove {tag}.
Backspace on an empty input removes the most recent tag.
The inline input forwards aria-invalid from invalid and uses the label / aria-label you supply.
Blurring with a draft value commits the tag automatically.
Duplicate tags are blocked by default; set unique={false} to allow them.

Recipes

Normalize entries inside onValueChange (e.g. lower-casing or trimming).
Use maxTags for filter-style inputs to keep queries predictable.
Use renderTag to render branded chips or include extra metadata per tag.