# Algolia DocSearch: a hosted search dropdown for documentation sites

> DocSearch crawls a documentation site, indexes the content in Algolia, and renders an accessible search box through @docsearch/js or @docsearch/react. It is free for eligible docs projects, but the index, the crawler and the credentials all live on Algolia's side.

**algolia/docsearch** — :blue_book: The easiest way to add search to your documentation.

- Repository: https://github.com/algolia/docsearch
- Website: https://docsearch.algolia.com
- Stars: 4,378 · Forks: 440
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/algolia-docsearch

## The problem DocSearch solves is the search box nobody wants to build

Documentation sites accumulate pages faster than they accumulate navigation. A static site generator gives you a sidebar and a next-page link, and that is usually where search stops. Building your own means running an indexer over Markdown, keeping the index in sync with every deploy, and writing a keyboard-accessible dropdown that does not fall apart on mobile. DocSearch takes the indexing half and the UI half and hands you a component.

The audience is narrow on purpose. The README describes it as "the easiest way to add search to your documentation, for free" and points applicants at docsearch.algolia.com/apply. The projects listed as users are public documentation sites: Bootstrap, Cheerio, Element Plus, Authelia, MDX, VitePress. That list tells you the shape of the intended user. If your content sits behind a login, or your site is a marketing page with twelve URLs, DocSearch is the wrong instrument.

## Crawl, index, render: the three moving parts

The README states the flow in one sentence: DocSearch crawls your documentation, pushes the content to an Algolia index, and provides a dropdown search experience on your website. Those are three separate systems, and only the third one lives in this repository.

The crawler is a different project. The README's related-projects list names algolia/docsearch-scraper as "DocSearch crawler that extracts data from your documentation", and algolia/docsearch-configs as the repository holding "DocSearch websites configurations that DocSearch powers". So the configuration that decides which URLs get crawled and which CSS selectors become records is not in algolia/docsearch. What is here is the front end: a monorepo whose workspaces cover adapters/*, packages/* and examples/*, with build targets for @docsearch/core, @docsearch/css, @docsearch/react, @docsearch/js, @docsearch/sidepanel, @docsearch/sidepanel-js, @docsearch/modal, @docsearch/docusaurus-adapter and @docsearch/cli.

At runtime the component talks to Algolia directly. You pass an appId, an apiKey and an array of index names; the widget queries those indices and renders hits in a dropdown. The README stresses that the container must be a div, not an input, because DocSearch generates the search box itself and handles the accessibility attributes. That is a real constraint, not a stylistic preference: if you hand it an input element you are fighting the component's own markup.

The repository also ships MCP plugins under mcp/plugins/docsearch, which the README says connect ChatGPT, Codex, Cursor and Claude Code to https://mcp.algolia.com/1/docsearch/mcp for public developer documentation. That is a separate consumption path from the dropdown, and it uses the same public index rather than your own.

## Installing @docsearch/js and getting a first search box running

The README gives two client packages. The JavaScript one is the framework-agnostic option, and the install line pins major version 5:

```bash
bun add @docsearch/js@5
# or
npm install @docsearch/js@5
```

If you would rather not use a package manager, the README offers a standalone script tag from jsDelivr at https://cdn.jsdelivr.net/npm/@docsearch/js@5. Either way you need a container element in your markup. The README's example is a plain div with an id:

```html
<div id="docsearch"></div>
```

Then you import the package and the stylesheet, and call docsearch() with the container plus your credentials. Note that the README uses placeholder strings for all three values; nothing in the repository supplies real ones, and the README sends you to the apply page first:

```js
import docsearch from '@docsearch/js';
import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indices: ['YOUR_INDEX_NAME'],
  apiKey: 'YOUR_SEARCH_API_KEY',
});
```

What you should see is the DocSearch button rendered inside that div. The README notes the container can be a CSS selector or an Element. It repeats the warning that you must pass a container such as a div and not an input, because the component builds the accessible search box for you.

The React path is the same shape with a different entry point. Install @docsearch/react@5, import the named DocSearch component and the CSS, and render it with the same three props:

```jsx
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices=["YOUR_ALGOLIA_INDEX"]
    />
  );
}
```

Both snippets come from the README. Neither will return results until credentials exist and an index has been populated, and the README does not document what the component does when the index is empty or the key is wrong. That is worth testing yourself before you ship.

## Where DocSearch stops being the right tool

The first limitation is structural: you do not own the index. Records are pushed to Algolia, queries go to Algolia, and the apiKey you embed is a search-only key tied to that account. If your requirement is that document text never leaves your infrastructure, no amount of client-side configuration fixes that.

The second is the crawler boundary. Because the scraper lives in algolia/docsearch-scraper and the per-site configuration lives in algolia/docsearch-configs, changing what gets indexed is not a change to this repository. If your docs are generated at build time with content that never appears in static HTML, or your site is a single-page app whose routes are not reachable by a crawler, the index will be thin regardless of how the dropdown looks.

The third is that the README does not document failure modes. There is no section on what happens when the index goes stale, how to trigger a recrawl, or how to roll back a bad configuration. Release notes for @docsearch/react, @docsearch/sidepanel and @docsearch/sidepanel-js at 5.1.1 are the only version signal in the repository, and they cover the client packages rather than the pipeline. Treat the crawler and index lifecycle as something you confirm with Algolia directly, not something you read off this repository.

## DocSearch versus running the scraper against your own search backend

The realistic alternative is to keep the same crawler model but point it at a backend you operate. Typesense's docsearch-scraper is the comparison that shows up in search data, and the difference is architectural rather than cosmetic: the crawler still walks your pages and extracts records, but the records land in your own Typesense instance instead of an Algolia index you do not control. You take on running and upgrading that instance, and you lose the hosted apply-for-credentials path.

The client side diverges too. DocSearch's front end is a specific dropdown component with its own styling hooks, and the README defers styling questions to docsearch.algolia.com/docs/styling rather than documenting them inline. A self-hosted setup usually means you also pick or build the UI. That is more work, and it is the trade you make for keeping the index on your own machines.

A third option is doing nothing and relying on your static site generator's built-in search. That is viable for small sites and stops being viable once the corpus crosses a few hundred pages, which is roughly where a dropdown with keyboard navigation starts earning its place.

## Licence and the cost of staying current

The client code in this repository is MIT, per the LICENSE file and the badge in the README. MIT covers the packages you install: @docsearch/js, @docsearch/react, @docsearch/css and the rest of the workspace list. It does not describe the terms of the hosted Algolia service, which is a separate agreement you enter when you apply. Nothing in the README or the repository states pricing, quotas or what happens to an index if an application is declined, and the search data around DocSearch pricing reflects that gap. Read the terms on the Algolia side before you build a dependency on it.

Upgrade cost is mostly a function of the monorepo's release cadence. The most recent releases noted in the repository are @docsearch/sidepanel@5.1.1, @docsearch/sidepanel-js@5.1.1 and @docsearch/react@5.1.1, all published on 2026-09-18, and the last push to the repository was on 2026-09-19. The install lines in the README pin major version 5, which means patch and minor upgrades are the expected path and a major bump is the one that will need attention. The monorepo uses Bun workspaces and a staged build script, so if you fork and build locally you inherit that toolchain rather than a plain npm build.

## Conclusion

Adopt DocSearch if your documentation is public, stable in URL structure, and you want a maintained search dropdown without running a search cluster; the client packages are MIT and the crawler configuration lives in algolia/docsearch-configs. Do not adopt it if you need a self-hosted index, private content, or per-query control over ranking, because the index and the crawler sit on Algolia's infrastructure and the README points to a separate repository for the scraper. Before wiring anything up, apply for credentials at docsearch.algolia.com/apply and confirm what your appId, apiKey and index name actually are, since the README's examples use placeholders.

## FAQ

### Is Algolia DocSearch free?

The README calls it "the easiest way to add search to your documentation, for free" and directs applicants to docsearch.algolia.com/apply, so access starts with an application rather than a purchase. The repository does not state quotas, pricing tiers or what happens after an application is reviewed.

### What is a DocSearch alternative if I want to host the index myself?

Typesense's docsearch-scraper appears in search data as the self-hosted counterpart: it keeps the crawl-and-extract model but writes records to a Typesense instance you operate instead of an Algolia index. The trade is that you run the backend and typically supply your own search UI, since DocSearch's dropdown is tied to Algolia credentials.

### How do I install DocSearch in a React app?

Install @docsearch/react@5, import the named DocSearch component together with @docsearch/css, and render it with appId, apiKey and indices props. The README's example uses placeholder strings for all three values, so you need credentials from the apply page before results appear.

### Can I use DocSearch without a package manager?

Yes. The README lists standalone script tags from jsDelivr for both clients, https://cdn.jsdelivr.net/npm/@docsearch/js@5 and https://cdn.jsdelivr.net/npm/@docsearch/react@5, as alternatives to installing the packages.

### Where is the DocSearch crawler source code?

It is not in this repository. The README's related-projects list names algolia/docsearch-scraper as the crawler and algolia/docsearch-configs as the repository holding the site configurations DocSearch powers.

### What does the DocSearch MCP endpoint do?

The README says the client plugins under mcp/plugins/docsearch connect ChatGPT, Codex, Cursor and Claude Code to https://mcp.algolia.com/1/docsearch/mcp for public developer documentation. It is a separate consumption path from the dropdown widget and points at public docs rather than a private index.

## Sources

- [algolia/docsearch on GitHub](https://github.com/algolia/docsearch)
- [License: MIT](https://github.com/algolia/docsearch/blob/main/LICENSE)
- [Project website](https://docsearch.algolia.com)
- [README](https://github.com/algolia/docsearch/blob/main/README.md)
- [Releases](https://github.com/algolia/docsearch/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/algolia-docsearch