Hybrid search boxPro

Search with keyword, semantic and hybrid modes, a weight slider that reranks live and scores that explain themselves.

Markdown

On this page

ProDrag the weight: the list reranks and each row shows the shares behind its score.

Installation

$ pnpm dlx shadcn@latest add @chatcn-pro/hybrid-search-box

Usage

tsx

import { HybridSearchBox } from "@/components/ui/chatcn/pro/hybrid-search-box"

<HybridSearchBox results={results} filters={types} onSubmit={search} />

Pass each result with both raw scores, keyword and semantic, each from 0 to 1. The box fuses them with the weight, so the list reranks as the slider moves without another request, and every row says why it ranked: matched terms, similarity, or the two shares behind its score. The bar beside each score shows those shares in gray and accent. When a mode finds nothing, the box says why and offers the mode most likely to help.

Examples

States

ProKeyword mode, no keyword match, searching, error and disabled.

Props

Prop	Type	Notes
`results`	`HybridResult[]`	`{ id, title, snippet, source?, kind?, keyword, semantic }`
`query`, `defaultQuery`, `onQueryChange`	`string`	Controlled or not
`mode`, `defaultMode`, `onModeChange`	`"keyword" \| "semantic" \| "hybrid"`	Default hybrid
`weight`, `defaultWeight`, `onWeightChange`	`number`	Semantic share, default 0.6
`filters`, `activeFilters`, `onActiveFiltersChange`	`{ id, label }[]`	Matches `kind`
`threshold`	`number`	Hide fused scores under it, default 0.2
`status`, `error`, `onRetry`	`"idle" \| "loading" \| "error"`	Request state
`onSubmit`	`(query, mode, weight) => void`	Enter in the field
`onSelect`	`(id) => void`	A result was opened
`disabled`	`boolean`	While the index builds
`labels`	`Partial<HybridSearchBoxLabels>`	Every string

Keyboard

Key	Action
Enter	Run the search (never while composing)
Escape	Clear the field
Arrow keys	Move between modes, or move the weight by 5%
Tab	Field, modes, weight, filters, then results

Accessibility

The box is a search landmark; modes are a toggle group and the weight is a slider that reads as a semantic percentage.
Filters are toggle buttons with aria-pressed.
The result count is announced politely when it changes, never per keystroke row.
Matched terms are underlined, not only bolded, so the match survives grayscale and high contrast.

Motion

When you drag the weight or pick a mode with a pointer, rows slide to their new rank in 220 ms so you can follow a result as it moves. Changes from the keyboard and reduced motion reorder instantly. Score bars resize with a 150 ms transition.