Migrating from Algolia to Headband

Then swap the front end, in 3 steps

1. 1

   Install @headband/react

   This is an InstantSearch-inspired React kit. If you've been using react-instantsearch with Algolia, the mental model will feel familiar, but this is not a drop-in replacement.

   npm i @headband/react

2. 2

   Replace algoliasearch(...) with headband(...)

   Your client initialization changes by one line. The API surface is intentionally similar.

   const searchClient = headband(
     'https://headband.dev',
     'hb_src_YOUR_SEARCH_KEY'
   );

3. 3

   Replace <InstantSearch> with <HeadbandProvider>

   Components have the same names where possible (<SearchBox>, <Hits>, <RefinementList>, <Pagination>) but wrapper props change from Algolia's searchClient/indexName shape to Headband's client/index shape.

   <HeadbandProvider
     client={searchClient}
     index="products"
   >
     <SearchBox />
     <Hits hitComponent={Hit} />
   </HeadbandProvider>

Side-by-side: SearchBox + Hits

import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch, SearchBox, Hits
} from 'react-instantsearch';

const searchClient = algoliasearch(
  'APP_ID', 'SEARCH_KEY'
);

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="products"
    >
      <SearchBox />
      <Hits hitComponent={Hit} />
    </InstantSearch>
  );
}

import {
  headband,
  HeadbandProvider,
  SearchBox,
  Hits
} from '@headband/react';

const searchClient = headband(
  'https://headband.dev',
  'hb_src_YOUR_SEARCH_KEY'
);

function App() {
  return (
    <HeadbandProvider
      client={searchClient}
      index="products"
    >
      <SearchBox />
      <Hits hitComponent={Hit} />
    </HeadbandProvider>
  );
}

The Hit component can stay small, but wrapper wiring and some refinement props should be reviewed against the Headband React docs.

Why migrate?

Four reasons to move:

• One engine per retrieval job

  A catalog on Meilisearch, autocomplete on Typesense, large corpora on Elasticsearch: each index on the engine that suits it, under one API and one key.

• Pricing escalation

  Algolia's pay-as-you-go bill rises with every search request and every record you store.

• Vendor lock-in

  Algolia's API is proprietary. Once your client code is shaped around it, leaving is a project, not a switch.

• Data sovereignty

  Bring your own Meilisearch, Typesense or Elasticsearch, and the index stays in your own cluster, under your own controls.

Feature mapping

SupportedSoon: on the roadmapNot yet: not in the API yet

What doesn't migrate yet

Being honest: Algolia has spent ten years building features that aren't a weekend port.

• AI Personalization

  Algolia's user-event-driven re-ranking is genuinely better than anything we ship today. On the roadmap, not shipping this quarter.

• Geo by IP address

  Algolia's aroundLatLngViaIP and automatic radius have no equivalent. Send the point and the radius yourself.

• Query Suggestions

  Basic version on the roadmap.

• Recommend / related items

  You can build one today with your own vectors and hybrid search on Elasticsearch or Meilisearch. A built-in version is on the roadmap.

If any of these are critical to your business right now, stay on Algolia for those features and migrate the rest. Headband is happy to be one of several layers in your stack.

Cost comparison

For a representative mid-size catalog (~500k records under 2 GB of JSON, ~2M monthly search operations):

An always-on engine is billed by its RAM only, so its searches and stored data cost nothing extra. Pro includes 4 GB of always-on RAM, and each GB above that is $15 a month. Size the engine to your index: on October 29, 2026 we measured 1M documents (about 1 GB of JSON) on our production hardware, and a 4 GB Meilisearch engine served 308 searches a second against 1,799 for 8 GB. A catalog near 2 GB of JSON has a larger index, so start at 8 GB and measure. The Algolia figure is our estimate from its published pay-as-you-go rates, not a quote.

The point isn't that we're always cheaper; for small workloads Algolia's free tier is fine. The point is the shape of the bill: Starter is $12 a month with 250,000 searches included, and past what a plan includes, searches cost between $0.01 and $0.03 per 1,000, less on bigger plans.

Next steps

• Compare the four engines on the same query, live, before you choose one.→
• Install @headband/react and follow the getting started guide.→
• Run an A/B test: assign variants and record outcomes with hosted experiments.→