Getting Started

Installation

npm install @requence/tokenized-search

All UI dependencies (react, react-dom, the @tiptap/* packages, and tailwind-merge) are optional peer dependencies, so installing the package pulls in none of them — a server that only parses queries via the core entry stays free of UI packages. To use the <TokenizedSearch /> component, install them alongside:

npm install react react-dom tailwind-merge \
  @tiptap/core @tiptap/pm @tiptap/react \
  @tiptap/extension-document @tiptap/extension-history \
  @tiptap/extension-paragraph @tiptap/extension-text

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)}
  ...
/>

Auto-commit

By default the search only commits when the user presses Enter or clicks the submit button. Pass autoCommit to fire onSearch on every change instead — with the technical query, once any async options have resolved — and hide the submit button. Useful when the query should apply immediately without a manual step:

<TokenizedSearch
  autoCommit
  tokens={tokens}
  onSearch={(segments, rawText) => applyFilter(rawText)}
/>

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