react-token-autocomplete

A style-agnostic token/tag autocomplete component for React. Ships with zero default styles — bring your own CSS, Tailwind, CSS modules, or any styling solution.

Install

npm install react-token-autocomplete

Requires React 18 or 19 as a peer dependency.

Quick Start

import { TokenAutocomplete } from 'react-token-autocomplete'

function App() {
  return (
    <TokenAutocomplete
      options={['React', 'Vue', 'Svelte', 'Angular', 'Solid']}
      placeholder="Add a framework..."
      onAdd={(value) => console.log('Added:', value)}
      onRemove={(value) => console.log('Removed:', value)}
    />
  )
}

Styling with Tailwind

Every element exposes a className prop — no style overrides or CSS specificity battles:

<TokenAutocomplete
  options={['React', 'Vue', 'Svelte']}
  className="flex flex-wrap items-center gap-1 border rounded-lg p-2 focus-within:ring-2 focus-within:ring-blue-500"
  inputClassName="outline-none flex-1 min-w-[120px] bg-transparent"
  tokenClassName="inline-flex items-center gap-1 bg-blue-100 text-blue-800 px-2 py-0.5 rounded-full text-sm"
  tokenRemoveClassName="hover:text-red-600 cursor-pointer text-blue-400"
  optionsClassName="absolute z-10 mt-1 w-full bg-white border rounded-lg shadow-lg max-h-60 overflow-auto"
  optionClassName="px-3 py-2 cursor-pointer hover:bg-gray-50"
  optionSelectedClassName="bg-blue-50"
  placeholderClassName="text-gray-400"
  processingClassName="animate-spin h-4 w-4 border-2 border-blue-500 border-t-transparent rounded-full"
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | string[] | — | Controlled value (see Controlled Mode) | | onChange | (values: string[]) => void | — | Called with full values array on every add/remove | | options | string[] | [] | Available options to select from | | defaultValues | string[] | [] | Initial selected tokens (uncontrolled mode only) | | placeholder | string | '' | Placeholder text when empty | | threshold | number | 0 | Min characters before showing suggestions | | processing | boolean | false | Show a loading indicator | | autoFocus | boolean | false | Focus input on mount | | filterOptions | boolean | true | Filter options by input text | | simulateSelect | boolean | false | Single-value select mode (hides input after selection) | | limitToOptions | boolean | false | Only allow values from options (no custom input) | | parseOption | (option: string) => ReactNode | — | Custom render for dropdown options | | parseToken | (token: string) => ReactNode | — | Custom render for tokens | | parseCustom | (value: string) => string | — | Transform custom input values | | onInputChange | (value: string) => void | — | Called when input text changes | | onAdd | (value: string) => void | — | Called when a token is added | | onRemove | (value: string, index: number) => void | — | Called when a token is removed |

className Props

| Prop | Element | |------|---------| | className | Outer container <div> | | inputClassName | Text <input> | | tokenClassName | Token <span> | | tokenRemoveClassName | Token remove <button> | | optionsClassName | Dropdown <ul> | | optionClassName | Each option <li> | | optionSelectedClassName | Currently highlighted option (added alongside optionClassName) | | placeholderClassName | Placeholder <span> | | processingClassName | Loading indicator <span> |

Keyboard Shortcuts

| Key | Action | |-----|--------| | Enter | Add the currently highlighted option | | Escape | Close the dropdown | | Backspace | Remove last token (when input is empty) | | ArrowUp / ArrowDown | Navigate options |

Controlled Mode / react-hook-form

The component supports both uncontrolled (defaultValues) and controlled (value + onChange) modes. Controlled mode works seamlessly with form libraries like react-hook-form.

Basic controlled usage

import { useState } from 'react'
import { TokenAutocomplete } from 'react-token-autocomplete'

function App() {
  const [tags, setTags] = useState<string[]>([])

  return (
    <TokenAutocomplete
      options={['React', 'Vue', 'Svelte']}
      value={tags}
      onChange={setTags}
    />
  )
}

With react-hook-form

The component forwards a ref to its internal <input> element, so react-hook-form's Controller can manage focus automatically.

import { useForm, Controller } from 'react-hook-form'
import { TokenAutocomplete } from 'react-token-autocomplete'

interface FormData {
  tags: string[]
}

function TagForm() {
  const { control, handleSubmit } = useForm<FormData>({
    defaultValues: { tags: [] },
  })

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <Controller
        name="tags"
        control={control}
        rules={{ validate: (v) => v.length > 0 || 'At least one tag required' }}
        render={({ field }) => (
          <TokenAutocomplete
            ref={field.ref}
            value={field.value}
            onChange={field.onChange}
            options={['React', 'Vue', 'Svelte', 'Angular', 'Solid']}
            placeholder="Add tags..."
            limitToOptions
          />
        )}
      />
      <button type="submit">Submit</button>
    </form>
  )
}

Note: onAdd and onRemove still fire alongside onChange, so you can use them for analytics or side effects without interfering with form state.

Headless Hook

For full control over rendering, use the useTokenAutocomplete hook:

import { useTokenAutocomplete } from 'react-token-autocomplete'

function CustomAutocomplete() {
  const {
    values,
    inputValue,
    availableOptions,
    showOptions,
    setInputValue,
    addValue,
    removeValue,
    handleKeyDown,
    handleOptionMouseEnter,
    handleOptionSelect,
    inputRef,
    containerRef,
    focus,
    selectedIndex,
  } = useTokenAutocomplete({
    options: ['React', 'Vue', 'Svelte'],
    onAdd: (v) => console.log('added', v),
  })

  return (
    <div ref={containerRef} onClick={focus}>
      {values.map((v, i) => (
        <span key={i}>
          {v}
          <button onClick={() => removeValue(i)}>&times;</button>
        </span>
      ))}
      <input
        ref={inputRef}
        value={inputValue}
        onChange={(e) => setInputValue(e.target.value)}
        onKeyDown={handleKeyDown}
        onFocus={focus}
      />
      {showOptions && (
        <ul>
          {availableOptions.map((opt, i) => (
            <li
              key={opt}
              onClick={() => handleOptionSelect(opt)}
              onMouseEnter={() => handleOptionMouseEnter(opt)}
              style={{ background: i === selectedIndex ? '#eee' : undefined }}
            >
              {opt}
            </li>
          ))}
        </ul>
      )}
    </div>
  )
}

Exports

// Components
import { TokenAutocomplete, Token, Options, Option } from 'react-token-autocomplete'

// Headless hook
import { useTokenAutocomplete } from 'react-token-autocomplete'

// Types
import type {
  TokenAutocompleteProps,
  TokenProps,
  OptionsProps,
  OptionProps,
  UseTokenAutocompleteOptions,
  UseTokenAutocompleteReturn,
} from 'react-token-autocomplete'

Development

npm install        # install dependencies
npm run dev        # run examples playground
npm run build      # build library (ESM + CJS + types)
npm test           # run unit tests
npm run test:watch # run unit tests in watch mode
npm run e2e        # run Playwright e2e tests (mobile, tablet, desktop)
npm run lint       # type-check with tsc

License

ISC