Getting Started

Installation

npm install @requence/tokenized-search

Tailwind CSS Setup

This package uses Tailwind CSS utility classes internally (via tailwind-merge). Add the @source directive to your CSS entry point so Tailwind scans the package for class names:

@import "tailwindcss";
@source "../node_modules/@requence/tokenized-search";

Basic Usage

import { TokenizedSearch } from '@requence/tokenized-search'

function App() {
  return (
    <TokenizedSearch
      tokens={[
        {
          key: 'status',
          label: 'Status',
          options: [
            { value: 'active', label: 'Active' },
            { value: 'inactive', label: 'Inactive' },
          ],
        },
        {
          key: 'source',
          label: 'Source',
          options: async (query, signal) => {
            const res = await fetch(`/api/sources?q=${query}`, { signal })
            return res.json()
          },
        },
      ]}
      onSearch={(segments, rawText) => {
        console.log(segments, rawText)
      }}
    />
  )
}

The component works out of the box with default styling. To customize the appearance, use slot sub-components.

Controlled vs Uncontrolled

Uncontrolled (default) — pass defaultValue to set the initial query:

<TokenizedSearch defaultValue="status:active" ... />

Controlled — pass value and onChange to manage state externally:

const [value, setValue] = useState('')

<TokenizedSearch
  value={value}
  onChange={(newValue, segments) => setValue(newValue)}
  ...
/>

Next Steps

• Token Definitions — configure token keys, options, and behavior
• Query Parsing — understand parsed segments and translation utilities
• Styling — customize appearance with compound slot components
• API Reference — full component props and slot reference