Browser SDK

@findlane/browser searches an index from the browser with its public ID. It has no dependencies and is about 1 KB.

Install

npm install @findlane/browser

Using React? @findlane/browser/react has a search box, a results page with filters, and hooks, in the same package.

Or, without a build step, load it with a script tag. It defines a global Findlane, so use new Findlane.SearchBrowserClient(...) instead of the import below. See Script tag.

<script src="https://cdn.findlane.dev/browser/0/findlane.min.js"></script>

Create a client

import { SearchBrowserClient } from "@findlane/browser"

const client = new SearchBrowserClient({ publicId: "pub_your_public_id" })

Browser search works from the index's allowed origins, or with a signed key; see Security.

search(request, options)

type Product = {
  objectID: string
  title: string
  brand: { name: string }
  price: number
  image: string
}

const results = await client.search<Product>(
  { q: "trail shoe", facets: ["brand.name"], limit: 24, highlight: true },
  { signal: controller.signal }
)

The type parameter types each hit's record. options.signal cancels the request.

Request

Response

multiSearch(queries, options)

Searches several indexes in one request (0.22.0): up to 10 searches, each with its index's public ID as index (this client's when left out), counted as one search for each workspace they search. Answers each search's results with its index, or its error and status, in order. See Several indexes in one request.

suggest(request, options)

For a search that found nothing, a query that finds results, or null. It takes the same request as search and needs the index's didYouMean setting. See Did you mean.

const suggestion = await client.suggest({ q: "prtien" })
// { q: "protein", applied: false, changes: [{ from: "prtien", to: "protein" }] }

querySuggestions(request, options)

Whole searches to offer as the visitor types, the best first (0.14.0). request is { q, limit? }, with limit from 1 to 10 (5 by default). Each suggestion is { q, typed }, where typed is the part of q that was typed, as UTF-16 offsets. See Query suggestions.

import { suggestionParts } from "@findlane/browser"

const suggestions = await client.querySuggestions({ q: "hrek" })
// [{ q: "hrekkjavöku búningar", typed: [0, 4] }]
suggestionParts(suggestions[0])
// [{ text: "hrek", typed: true }, { text: "kjavöku búningar", typed: false }]

They don't count as searches, so ask on each pause in typing, with the same signal as the search.

popularSearches(options)

The index's popular searches, for an empty search box, with the owner's pinned searches first (0.14.0). Empty until the index has enough searches. The list changes daily, so the client asks once per limit (6 by default) and keeps the answer.

const popular = await client.popularSearches({ limit: 6 })
// [{ q: "gríma" }, { q: "latex" }]

warm()

Opens the connection to the API before the first search needs it, as a preconnect hint in the page would (0.16.0). Call it when the shopper focuses the search box; the React components do. It does something once per page, and nothing outside a browser.

input.addEventListener("focus", () => client.warm(), { once: true })

tilesFor(box, zoom)

The fixed map tiles covering a map's view, for tile in a search (0.33.0). It's a function of the package rather than the client's. In React, useMapSearch calls it for you.

import { tilesFor } from "@findlane/browser"

const tiles = tilesFor({ north: 64.17, south: 64.12, east: -21.8, west: -22 }, 13.6)
// [{ z: 12, x: 1797, y: 1087 }, …]

• box is a plain { north, south, east, west } in degrees, or a map library's own bounds object with getNorth() and the like, such as MapLibre's, Mapbox's or Leaflet's (0.34.0). West greater than east crosses the antimeridian. Any other box throws a TypeError.
• zoom is the map's. Tiles are one level above it, at most six on a desktop screen, and at most 16 for a box much wider than its zoom, which gets larger tiles.
• In a script tag, it's Findlane.tilesFor (0.34.0).

clusterFor(place, clusters)

The cluster a record is in, from the clusters of its tile, for one marker an area (0.34.0). Give clusters and spread the same cells. It's undefined when none holds the place.

import { clusterFor } from "@findlane/browser"

const { clusters, hits } = await client.search({ tile, limit: 50, clusters: { cells: 8 }, spread: { cells: 8 } })
for (const hit of hits) {
  const cluster = clusterFor(hit.record._geoloc, clusters)
  // Draw the hit's photo, with cluster.count - 1 others there.
}

A cluster's bounds are rounded, so comparing a place with them directly misses records on an edge. In a script tag, it's Findlane.clusterFor.

imageUrl(src, width)

An image's address resized by optimized images (0.27.0): src resized to width CSS pixels (rounded up to one of the widths Findlane makes) and sent as WebP from images.findlane.dev (0.28.0), when the index has optimized images on and src is on one of its image hosts. Otherwise it returns src as it is. The client learns the hosts from search answers, so build image addresses from results. It remembers where an index's images come from in the browser, and opens that connection with warm() and the first search on later pages. Load images with crossorigin="anonymous", so they use it.

img.src = client.imageUrl(hit.record.image, 240)
img.srcset = `${client.imageUrl(hit.record.image, 240)} 1x, ${client.imageUrl(hit.record.image, 480)} 2x`
img.crossOrigin = "anonymous"

Each hit's placeholder is a preview of its image: placeholderUrl(hit.placeholder) draws it as a PNG data address, and placeholderCss and revealCss (0.27.1) are the styles while the image loads and as it sharpens in. Optimized images shows them together.

recentSearches

The visitor's recent searches, kept in their browser's localStorage per public ID, and never sent to Findlane (0.14.0): list(limit?) (5 by default, the newest first), add(q), remove(q), and clear(). It keeps up to 10, without repeats.

recommendations(objectID, options)

A product's Goes with, Similar and Bought together lists, for indexes with the recommendations add-on. Options are the request's other fields.

const { ready, goesWith, similar, together } = await client.recommendations("sku-123", { limit: 6 })

list(id, options)

One of the index's lists, such as popular: a row of products (hits) or a field's values with their counts (values), with its title and browse (its filters and sort, for a "See all" link). Built ahead and answered from a cache near the visitor, so it isn't counted as a search (0.15.0). options.limit gives fewer than the list holds. An index without the list throws a FindlaneError with status 404.

lists(ids, options)

Several lists in one request, up to 10, in the order asked; IDs the index has no list for are left out. Without IDs, all of the index's lists (0.15.0).

const [halloween, themes] = await client.lists(["halloween", "themes"])

events

Views, clicks, add-to-carts and orders, for the Events tab in Analytics and Bought together (0.8.0). They're sent in the background and never throw. See Events.

client.events.click(hit.id, { query, position: index + 1, filters })

Errors

A failed request throws a FindlaneError with the HTTP status and the API's message:

import { FindlaneError } from "@findlane/browser"

try {
  await client.search({ q })
} catch (error) {
  if (error instanceof FindlaneError && error.status === 429)
    showMessage("Too many searches, try again shortly")
  else throw error
}

A cancelled request rejects with the AbortError from fetch.

Script tag

No build step needed: load the SDK from cdn.findlane.dev, and it 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" })

  client.search({ q: "jacket", limit: 10 }).then(({ hits }) => {
    for (const hit of hits) console.log(hit.record.title)
  })
</script>

In a module script, import it instead:

<script type="module">
  import { SearchBrowserClient } from "https://cdn.findlane.dev/browser/0/findlane.mjs"

  const client = new SearchBrowserClient({ publicId: "pub_your_public_id" })
  const { hits } = await client.search({ q: "jacket" })
</script>

browser/0/ always serves the latest 0.x release. To stay on one release, pin its version, and add its integrity hash so the browser checks the file:

<script
  src="https://cdn.findlane.dev/browser/0.34.0/findlane.min.js"
  integrity="sha384-VHEpSimqxx1A5HEA+qokMhGHWX2cjNASxVW+Y46AvJNU8Ef6ixtAZBji8qptS8zW"
  crossorigin="anonymous"
></script>

browser/versions.json lists every release with its hashes.