Quickstart

Get DocSearch integrated into your documentation site in just a few minutes. This guide will walk you through installing DocSearch and implementing search for both JavaScript and React applications.

Don’t have your Algolia credentials yet? Apply to DocSearch to get free access for your open-source documentation.

What You’ll Need

Before you begin, you’ll need:

An Algolia Application ID (appId)
An Algolia Search-Only API Key (apiKey)
Your DocSearch Index Name (indexName)

If you’re using the free DocSearch program, you’ll receive these credentials after your application is approved.

Choose Your Implementation

DocSearch is available as both a vanilla JavaScript package and a React component. Choose the implementation that matches your documentation framework:

JavaScript

For vanilla JavaScript, HTML sites, or any framework

React

For React, Next.js, Gatsby, or React-based frameworks

JavaScript Implementation

Installation

Install the JavaScript package using your preferred package manager:

npm install @docsearch/js@4

yarn add @docsearch/js@4

pnpm add @docsearch/js@4

Alternatively, you can use the CDN version without a package manager:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>

Add a Container

Add a container element to your HTML where DocSearch will render:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Documentation</title>
</head>
<body>
  <header>
    <!-- DocSearch will render here -->
    <div id="docsearch"></div>
  </header>

  <main>
    <!-- Your documentation content -->
  </main>

  <script type="module" src="/main.js"></script>
</body>
</html>

Use a container element like <div>, not an <input>. DocSearch generates a fully accessible search box for you.

Initialize DocSearch

Import and initialize DocSearch with your credentials:

main.js

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

const instance = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});

Programmatic Control

The docsearch() function returns an instance with methods for programmatic control:

// Open the search modal
instance.open();

// Close the search modal
instance.close();

// Check if modal is open
console.log(instance.isOpen); // true or false

// Check if instance is ready
console.log(instance.isReady); // true or false

// Clean up when done
instance.destroy();

Complete Example

Here’s a complete working example:

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

const docsearchInstance = docsearch({
  container: '#docsearch',
  appId: 'PMZUYBQDAK',
  indexName: 'docsearch',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  
  // Optional: Customize placeholder
  placeholder: 'Search documentation...',
  
  // Optional: Lifecycle callbacks
  onReady: () => {
    console.log('DocSearch is ready!');
  },
  onOpen: () => {
    console.log('Search modal opened');
  },
  onClose: () => {
    console.log('Search modal closed');
  },
});

// Expose for debugging
window.docsearch = docsearchInstance;

React Implementation

Installation

Install the React package using your preferred package manager:

npm install @docsearch/react@4

yarn add @docsearch/react@4

pnpm add @docsearch/react@4

Alternatively, use the CDN version:

<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@4"></script>

Basic Usage

Import the DocSearch component and render it in your application:

App.jsx

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

function App() {
  return (
    <div>
      <header>
        <DocSearch
          appId="YOUR_APP_ID"
          indexName="YOUR_INDEX_NAME"
          apiKey="YOUR_SEARCH_API_KEY"
        />
      </header>
      
      <main>
        {/* Your documentation content */}
      </main>
    </div>
  );
}

export default App;

TypeScript Support

DocSearch has full TypeScript support with type definitions included:

App.tsx

import { DocSearch } from '@docsearch/react';
import type { DocSearchProps } from '@docsearch/react';
import '@docsearch/css';
import type { JSX } from 'react';

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

export default App;

Using a Ref

Access the DocSearch instance programmatically using a ref:

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

function App() {
  const docSearchRef = useRef(null);

  const handleOpenSearch = () => {
    // Programmatically open the search modal
    docSearchRef.current?.open();
  };

  return (
    <div>
      <button onClick={handleOpenSearch}>
        Open Search
      </button>
      
      <DocSearch
        ref={docSearchRef}
        appId="YOUR_APP_ID"
        indexName="YOUR_INDEX_NAME"
        apiKey="YOUR_SEARCH_API_KEY"
      />
    </div>
  );
}

Complete Example

Here’s a complete React example with customization:

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

function App() {
  return (
    <DocSearch
      appId="PMZUYBQDAK"
      indexName="docsearch"
      apiKey="24b09689d5b4223813d9b8e48563c8f6"
      
      // Customize button text
      translations={{
        button: {
          buttonText: 'Search docs',
          buttonAriaLabel: 'Search documentation',
        },
      }}
      
      // Enable Algolia Insights
      insights={true}
      
      // Customize placeholder
      placeholder="Search documentation..."
      
      // Limit results per group
      maxResultsPerGroup={5}
    />
  );
}

export default App;

Verify It’s Working

After implementing DocSearch, you should see:

Search Button Appears

A search button with the text “Search” (or your custom text) and keyboard shortcut hint (Ctrl+K or ⌘K) appears in your application.

Modal Opens on Click

Clicking the search button or pressing Ctrl+K (⌘K on Mac) opens the search modal.

Search Returns Results

Typing a query returns relevant results from your documentation index.

Navigation Works

Clicking a result navigates to the corresponding documentation page.

If you’re not seeing results, verify that:

Your credentials are correct
Your index has been crawled and contains documents
Your API key has search permissions for the index

Import Styles

Both implementations require importing the CSS styles. DocSearch provides styles as a separate package:

import '@docsearch/css';

The styles include:

Search button styling
Modal and overlay styling
Result list styling
Responsive design for mobile devices
Dark mode support (automatic based on system preferences)

Keyboard Shortcuts

DocSearch comes with built-in keyboard shortcuts:

Shortcut	Action
`Ctrl+K` / `⌘K`	Open search modal
`/`	Open search modal
`Esc`	Close search modal
`↑` / `↓`	Navigate results
`Enter`	Go to selected result
`Tab`	Navigate to next section
`Shift+Tab`	Navigate to previous section

You can customize which shortcuts are enabled:

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  keyboardShortcuts: {
    'Ctrl/Cmd+K': true,  // Enable Ctrl/Cmd+K
    '/': false,           // Disable / shortcut
  },
});

Next Steps

Now that you have DocSearch working, explore these features:

Styling

Customize colors, fonts, and layout to match your brand

API Reference

Explore all configuration options and methods

Advanced Features

Learn about transformItems, custom components, and more

Ask AI

Enable AI-powered conversational search

Troubleshooting

Search button not appearing

Make sure you’ve:

Imported the CSS: import '@docsearch/css';
Provided a valid container selector
Called docsearch() after the DOM is ready

No search results

Check that:

Your Algolia credentials are correct
The index name matches your DocSearch index
Your index has been crawled and populated
Your API key has search permissions

Styles not loading

Ensure:

You’ve imported @docsearch/css in your entry file
Your bundler is configured to handle CSS imports
The CSS is loaded before rendering the component

TypeScript errors

DocSearch includes TypeScript definitions. Make sure:

You’re using @docsearch/react@4 or @docsearch/js@4
Your tsconfig.json includes the node_modules directory
You’re importing types correctly: import type { DocSearchProps } from '@docsearch/react';

Get Help

If you need assistance:

Check the API Reference for detailed documentation
Browse examples on GitHub
Visit the DocSearch website
Join the Algolia Community

Get Started

Installation

Core Concepts

Guides

Advanced

What You’ll Need

Choose Your Implementation

JavaScript

React

JavaScript Implementation

Installation

Add a Container

Initialize DocSearch

Programmatic Control

Complete Example

React Implementation

Installation

Basic Usage

TypeScript Support

Using a Ref

Complete Example

Verify It’s Working

Import Styles

Keyboard Shortcuts

Next Steps

Styling

API Reference

Advanced Features

Ask AI

Troubleshooting

Search button not appearing

No search results

Styles not loading

TypeScript errors

Get Help

​What You’ll Need

​Choose Your Implementation

JavaScript

React

​JavaScript Implementation

​Installation

​Add a Container

​Initialize DocSearch

​Programmatic Control

​Complete Example

​React Implementation

​Installation

​Basic Usage

​TypeScript Support

​Using a Ref

​Complete Example

​Verify It’s Working

​Import Styles

​Keyboard Shortcuts

​Next Steps

Styling

API Reference

Advanced Features

Ask AI

​Troubleshooting

​Search button not appearing

​No search results

​Styles not loading

​TypeScript errors

​Get Help

What You’ll Need

Choose Your Implementation

JavaScript Implementation

Installation

Add a Container

Initialize DocSearch

Programmatic Control

Complete Example

React Implementation

Installation

Basic Usage

TypeScript Support

Using a Ref

Complete Example

Verify It’s Working

Import Styles

Keyboard Shortcuts

Next Steps

Troubleshooting

Search button not appearing

No search results

Styles not loading

TypeScript errors

Get Help