Skip to main content
DocSearch is built on Algolia’s powerful search infrastructure, combining a web crawler, search API, and customizable UI components to deliver instant search for documentation sites.

​
Architecture Overview

DocSearch consists of three main components that work together:
1

Web Crawler

The Algolia Crawler extracts content from your documentation pages using configurable CSS selectors and builds a searchable index.
2

Algolia Search Index

Your documentation content is stored in an Algolia index, optimized for fast, typo-tolerant search with ranking and filtering capabilities.
3

Search UI Components

React or JavaScript components integrate into your site, providing a modal search interface with keyboard shortcuts and AI-powered answers.

​
Search Flow

When a user searches your documentation, here’s what happens:

​
1. Query Input

As users type in the search box, DocSearch sends queries to Algolia with debouncing to optimize performance: 
import { DocSearch } from '@docsearch/react';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indexName="YOUR_INDEX_NAME"
    />
  );
}

​
2. Search Processing

Algolia processes the query using:
  • Typo tolerance: Handles misspellings automatically
  • Prefix matching: Returns results as you type
  • Ranking algorithm: Orders results by relevance
  • Highlighting: Emphasizes matching terms

​
3. Results Rendering

Results are grouped by hierarchy level (headings, content) and displayed in the modal: 
interface DocSearchHit {
  objectID: string;
  content: string | null;
  url: string;
  hierarchy: {
    lvl0: string | null;
    lvl1: string | null;
    lvl2: string | null;
    lvl3: string | null;
    lvl4: string | null;
    lvl5: string | null;
    lvl6: string | null;
  };
}

​
Component Integration

DocSearch integrates with your site through a React provider pattern: 
import { DocSearch as DocSearchProvider } from '@docsearch/core';
import { DocSearchModal } from '@docsearch/react';

function DocSearchComponent(props) {
  return (
    <DocSearchProvider {...props}>
      <DocSearchInner {...props} />
    </DocSearchProvider>
  );
}
The provider manages:
  • Modal state: Open/closed status
  • Keyboard shortcuts: Cmd+K, / to open
  • Search queries: Input and results
  • Navigation: Moving between results
  • Ask AI state: Toggle between search and AI modes
The DocSearch component is fully accessible with ARIA attributes and keyboard navigation support.

​
State Management

DocSearch uses React hooks to manage state: 
export type DocSearchState = 'modal-askai' | 'modal-search' | 'ready' | 'sidepanel';

export interface DocSearchContext {
  docsearchState: DocSearchState;
  isAskAiActive: boolean;
  isModalActive: boolean;
  openModal: () => void;
  closeModal: () => void;
  onAskAiToggle: (active: boolean) => void;
}

​
State Transitions

ready → modal-search (user opens search)
modal-search → modal-askai (user activates Ask AI)
modal-askai → modal-search (user returns to search)
modal-search → ready (user closes modal)
modal-search → sidepanel (Ask AI on desktop with sidepanel support)

​
Programmatic API

You can control DocSearch programmatically using refs: 
import { DocSearch } from '@docsearch/react';
import { useRef } from 'react';
import type { DocSearchRef } from '@docsearch/core';

function App() {
  const searchRef = useRef<DocSearchRef>(null);

  return (
    <>
      <button onClick={() => searchRef.current?.open()}>
        Open Search
      </button>
      <button onClick={() => searchRef.current?.openAskAi()}>
        Ask AI
      </button>
      <DocSearch
        ref={searchRef}
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
      />
    </>
  );
}

​
Available Methods

interface DocSearchRef {
  /** Opens the search modal */
  open: () => void;
  /** Closes the search modal */
  close: () => void;
  /** Opens Ask AI mode */
  openAskAi: (initialMessage?: InitialAskAiMessage) => void;
  /** Opens the sidepanel directly */
  openSidepanel: (initialMessage?: InitialAskAiMessage) => void;
  /** Component ready state */
  readonly isReady: boolean;
  /** Modal open state */
  readonly isOpen: boolean;
  /** Sidepanel open state */
  readonly isSidepanelOpen: boolean;
}

​
Search Parameters

Customize search behavior with parameters: 
import { DocSearch } from '@docsearch/react';

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  searchParameters={{
    hitsPerPage: 20,
    attributesToRetrieve: ['hierarchy', 'content', 'url'],
    distinct: true,
    facetFilters: ['version:v3', 'language:en'],
  }}
/>
Search parameters are passed directly to the Algolia search client for advanced query customization.
Search across multiple indices for versioned documentation: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'docs_v4',
      searchParameters: { facetFilters: ['version:v4'] }
    },
    {
      name: 'docs_v3',
      searchParameters: { facetFilters: ['version:v3'] }
    }
  ]}
/>

​
Performance Optimizations

DocSearch includes several optimizations:
  • Debounced queries: Reduces API calls while typing
  • Request caching: Stores recent results
  • Lazy loading: Components load on demand
  • Virtual scrolling: Efficient rendering of large result sets
  • Prefetching: Loads resources on hover
The DocSearch component requires a valid Algolia API key and app ID. Keep your search API key public-safe (search-only permissions).

​
Next Steps

Indexing

Learn how the crawler indexes your documentation

Ask AI

Enable AI-powered answers for your search

Styling

Customize the appearance of DocSearch

API Reference

Explore all configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us