react-mini-search

A tiny, dependency-light React search UI powered by MiniSearch and Tailwind CSS. Exported components provide an inline search box and a keyboard-accessible search dialog suitable for docs, apps, and component libraries.

Features

• Lightweight client-side full-text search using minisearch.
• Ready-to-use components: InlineSearchand SearchDialog
• Fully typed with TypeScript and exportable types .
• Tailwind CSS for styling; build step generates a distributable styles.css.

Installation

Install peer dependencies in your project (React >= 17) and then add this package as a dependency. Example using pnpm:

pnpm add -D @ozbart/react-mini-search

Quick start

Example documents (each document must have an id and title):

const docs = [
  { id: 1, title: 'Getting Started', description: 'Intro docs', url: '/getting-started' },
  { id: 2, title: 'API', description: 'Reference docs', url: '/api' },
]

import { InlineSearch, SearchDialog } from 'react-mini-search'

// Inline
<InlineSearch
  documents={docs}
  fields={["title", "description"]}
  storeFields={["title", "description", "url"]}
  placeholder="Search docs..."
  onResultClick={(res) => { if (res.url) window.location.href = res.url }}
/>

// Dialog (provides a / Ctrl/Cmd+K keyboard shortcut)
<SearchDialog
  documents={docs}
  fields={["title", "description"]}
  storeFields={["title", "description", "url"]}
  placeholder="Search documentation..."
  onResultSelect={(res) => console.log('selected', res)}
/>

API

Exports (from src/index.ts):

• InlineSearch — Inline search component.
• SearchDialog — Modal search dialog with keyboard shortcut and selectable results.
• SearchTrigger — Small trigger component (bar/button) for opening the dialog.
• Types: Document, Result, UseSearchProps.

Types and important props (summary):

• Document

  • id (string | number) — required
  • title (string) — required
  • optional fields: url, description, category, icon, and any metadata

• UseSearchProps

  • documents: T[] — array of documents
  • fields: (keyof T)[] — fields to index/search
  • storeFields: (keyof T)[] — fields to include in search results
  • searchOptions?: MiniSearch.SearchOptions — pass-through to MiniSearch

• SearchComponentProps (used by InlineSearch and SearchDialog)

  • placeholder?: string
  • onResultClick?: (result) => void — InlineSearch
  • onResultSelect?: (result) => void — SearchDialog
  • debounceMs?: number — default 300
  • minQueryLength?: number — default 2
  • showClearButton?: boolean
  • emptyStateMessage?: string
  • loadingMessage?: string
  • className?: string, resultClassName?: string, renderResult?: (result) => React.ReactNode

For full prop and type details see src/lib/type.ts.

Development

Scripts are defined in package.json and expect pnpm:

• pnpm build — build JS (via tsup) and CSS (tailwind) to dist/.
• pnpm build:js — build JS only.
• pnpm build:css — build Tailwind CSS to dist/styles.css.
• pnpm format — format with Biome.
• pnpm check — run biome checks.

Example local build:

pnpm install
pnpm build

Bundling / Distribution

The package exposes dist/index.mjs and dist/index.d.ts. A styles.css build artifact is available at dist/styles.css and can be imported directly:

import 'react-mini-search/styles.css'

Notes & Recommendations

• MiniSearch runs in the browser and keeps an in-memory index. It's great for small to medium-sized datasets. For very large datasets prefer a server-side search service.
• Ensure fields and storeFields are chosen to include searchable text and any metadata your render functions use.
• The SearchDialog listens for Ctrl/Cmd + K to open. If you have another global shortcut, adapt or disable it.

Contributing

Contributions are welcome. Open issues or PRs for bug fixes, small features, or documentation improvements.