@findlane/browser
The Findlane browser SDK: fast, typo-tolerant search from the browser with an index's public ID. No dependencies, about 1 KB, plus optional React hooks and components.
Docs: https://findlane.dev/docs/browser-sdk
Install
npm install @findlane/browser
Quick start
import { SearchBrowserClient } from "@findlane/browser"
const client = new SearchBrowserClient({ publicId: "pub_your_public_index_id" })
const results = await client.search({ q: "trail shoe", limit: 10, highlight: true })
// results.hits[0].highlights?.title: "Trail <mark>shoe</mark>" (HTML-escaped, safe to insert as HTML)
Without a build step, load it with a script tag, which defines a global Findlane:
<script src="https://cdn.findlane.dev/browser/0/findlane.min.js"></script>
<script>
const client = new Findlane.SearchBrowserClient({ publicId: "pub_your_public_id" })
</script>
Each index has a copyable public ID in the dashboard. An owner must save allowed origins for the index before browser search is enabled.
Query suggestions
Whole searches to offer as visitors type, and the index's popular searches for an empty box. They don't count as searches. Recent searches stay in the visitor's browser.
await client.querySuggestions({ q: "hrek" }) // [{ q: "hrekkjavöku búningar", typed: [0, 4] }]
await client.popularSearches() // [{ q: "gríma" }, { q: "latex" }]
client.recentSearches.add("hárkolla")
React
@findlane/browser/react has a search box that suggests searches and results as visitors type, a results page with filters, and the hooks behind them, for React 18.2 and 19. Pages that don't import it don't load it.
import { SearchBox } from "@findlane/browser/react"
import "@findlane/browser/react/styles.css" // optional
<SearchBox publicId="pub_your_public_id" getHref={(hit) => hit.record.url} action="/search"
querySuggestions={4} popularSearches={6} recentSearches />
SearchDialog is the same search box in a dialog that ⌘K opens, as on docs sites. A results page shares its state through SearchProvider, with RefinementList, SortSelect, Hits, LoadMore, and hooks such as useRefinementList and useRange for your own markup. With routing, the search is kept in the URL. @findlane/browser/react/ssr renders the first results on the server. On a product page, useProductView(objectID), or <ProductView> in a server component, sends the page's view for the index's Events page. Docs: https://findlane.dev/docs/react
Search requests
| Option | |
|---|---|
q | The query. Words match with typos and as prefixes, depending on the index's settings. |
filters | Field values to keep: a value, { in: [...] }, or a range { gte, lte } for numbers and dates. |
facets | Fields to count values for, such as ["brand.name"]. |
disjunctiveFacets | Facets counted without the filter on their own field, so a list of checkboxes keeps its other values. |
sort | A sort ID from the index settings, or "relevance". |
limit, offset | Paging: up to 50 hits a request, and offsets up to 1,000. |
countMode, facetMode | "page" (the default, fastest) or "exact" for totals and facet counts across every match. |
highlight | true to wrap matched words in <mark>, or { preTag, postTag }. |
attributesToRetrieve | Return only these fields. |
A response has hits (each with its record and any highlights), total, facets, and tookMs. Pass { signal } as a second argument to cancel a request, as search-as-you-type should.
Events
client.events sends views, clicks, add-to-carts and orders in the background, for the index's Events page and Bought together. With visitorIds: true, they also carry random IDs for the browser and the visit, when the index takes them, and client.events.forget() deletes the IDs and asks for their events to be deleted. Docs: https://findlane.dev/docs/events
Security
The public ID grants search access only to its index, and it is visible in browser source. By default the API returns every uploaded record field. attributesToRetrieve requests fewer fields for speed, but it does not make the others private. Origin checks constrain browsers; they do not authenticate other callers. Keep public catalog fields safe to expose. The dashboard can remove origins, add server-enforced restrictions, or rotate the ID.
For logged-in people, pass signedKey: a short-lived key your server signs with the server SDK's signSearchKey, or a function that fetches one. Its restrictions replace the index's public settings. See Logged-in visitors.
Errors
Failed requests throw a FindlaneError with the HTTP status and the API's message:
- 403: this origin isn't allowed.
- 429: the public search rate limit.
- 402: the workspace has used its monthly searches.
License
MIT