@lumosearch/react

Drop-in React search component for LumoSearch Cloud.

Installation

npm install @lumosearch/react

Quick Start

import { LumoSearchBox } from '@lumosearch/react'
import '@lumosearch/react/styles.css'

function App() {
  return (
    <LumoSearchBox
      publicKey="pk_search_..."
      collection="products"
      placeholder="Search products..."
      onSelect={(result) => {
        console.log('Selected:', result.item)
      }}
    />
  )
}

With Provider (shared config)

import { LumoSearchProvider, LumoSearchBox } from '@lumosearch/react'
import '@lumosearch/react/styles.css'

function App() {
  return (
    <LumoSearchProvider config={{
      publicKey: "pk_search_...",
      collection: "products",
    }}>
      <Header />
      <SearchPage />
    </LumoSearchProvider>
  )
}

function Header() {
  return <LumoSearchBox placeholder="Quick search..." limit={5} />
}

Props

<LumoSearchBox />

| Prop | Type | Default | Description | |------|------|---------|-------------| | publicKey | string | — | Public search API key | | collection | string | — | Collection slug or ID | | apiUrl | string | https://api.lumosearch.com | API host URL | | placeholder | string | "Search..." | Input placeholder | | debounceMs | number | 250 | Debounce delay in ms | | limit | number | 8 | Max results to show | | autocomplete | boolean | false | Use autocomplete endpoint | | onSelect | (result) => void | — | Called when result is selected | | onQueryChange | (query) => void | — | Called when query changes | | titleField | string | auto | Field to use as result title | | descriptionField | string | — | Field to use as description | | showResponseTime | boolean | true | Show response time badge | | autoFocus | boolean | false | Auto-focus input on mount | | renderResult | (result, highlighted) => ReactNode | — | Custom result renderer | | renderEmpty | () => ReactNode | — | Custom empty state | | renderLoading | () => ReactNode | — | Custom loading state | | className | string | — | Container class | | inputClassName | string | — | Input class | | resultsClassName | string | — | Results dropdown class | | resultClassName | string | — | Result item class |

Keyboard Navigation

• ↓ / ↑ — Navigate results
• Enter — Select highlighted result
• Escape — Close dropdown

Custom Styling

Import the default styles or override with your own:

// Use default styles
import '@lumosearch/react/styles.css'

// Or use className props for Tailwind
<LumoSearchBox
  inputClassName="w-full rounded-lg border px-4 py-3"
  resultsClassName="absolute mt-1 rounded-lg border shadow-lg"
  resultClassName="px-4 py-2 hover:bg-gray-50"
/>

Custom Result Rendering

<LumoSearchBox
  publicKey="pk_search_..."
  collection="products"
  renderResult={(result, highlighted) => (
    <div className="flex items-center gap-3">
      <img src={result.item.image} className="w-10 h-10 rounded" />
      <div>
        <div className="font-medium">{highlighted}</div>
        <div className="text-sm text-gray-500">${result.item.price}</div>
      </div>
    </div>
  )}
/>

License

MIT