Migration guide
Migrating from Algolia to Headband
A short, honest guide for Algolia refugees. Migrating is the easy part — most teams finish in a couple of hours. The real upgrade is what comes after: instead of routing every retrieval job through one engine, you give each one — public search, faceted filtering, autocomplete, RAG, agent tool-calls — the engine that wins it. Here's how.
Why migrate?
Four reasons we hear over and over:
1.One engine per retrieval job
Algolia runs every workload through one engine. With Headband, public search can run on Typesense, faceted filtering and analytics on Elasticsearch, autocomplete on Meilisearch, and RAG or agent tool-calls on vector-tuned indexes -- same API, same dashboard, same client code. Each retrieval job gets the engine that wins it instead of one engine forced on all of them.
2.Pricing escalation
Algolia's PAYG model is fine until you're successful, at which point your search bill grows faster than your revenue. We've talked to teams whose monthly Algolia spend went from $200 to $4,000 in eighteen months without any real change in product behavior.
3.Vendor lock-in
Algolia's API is proprietary. Once your client code is shaped around it, leaving is a project, not a switch.
4.Data sovereignty
Your search index is a copy of your data sitting on someone else's infrastructure. Bring your own engine and the index stays in your cluster, encrypted -- a compliance win for some teams, and just one less copy to worry about for everyone else.
The 3-step migration
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/reactReplace algoliasearch(...) with headband(...)
Your client initialization changes by one line. The API surface is intentionally similar.
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.
Side-by-side: SearchBox + Hits
Before (Algolia)
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>
);
}After (Headband)
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.
Feature mapping
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.
A/B testing
Coming soon, but for now you'll need an external experimentation tool.
Query Suggestions
Basic version on the roadmap.
Recommend / related items
Vector-based version possible today via the underlying engine, polished product 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, ~2M monthly search operations):
The point isn't that we're always cheaper -- for small workloads Algolia's free tier is fine. The point is that Headband's price doesn't escalate with success, because it isn't priced per search.
Next steps
Stuck? Open an issue or email us. We answer.
Get started free