> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/algolia/docsearch/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get DocSearch up and running in your documentation site in minutes
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](https://docsearch.algolia.com/apply) 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:
For vanilla JavaScript, HTML sites, or any framework
For React, Next.js, Gatsby, or React-based frameworks
## JavaScript Implementation
### Installation
Install the JavaScript package using your preferred package manager:
```bash npm theme={null}
npm install @docsearch/js@4
```
```bash yarn theme={null}
yarn add @docsearch/js@4
```
```bash pnpm theme={null}
pnpm add @docsearch/js@4
```
Alternatively, you can use the CDN version without a package manager:
```html theme={null}
```
### Add a Container
Add a container element to your HTML where DocSearch will render:
```html index.html theme={null}
My Documentation
```
Use a container element like `
`, **not** an ``. DocSearch generates a fully accessible search box for you.
### Initialize DocSearch
Import and initialize DocSearch with your credentials:
```javascript main.js theme={null}
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:
```javascript theme={null}
// 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:
```javascript theme={null}
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:
```bash npm theme={null}
npm install @docsearch/react@4
```
```bash yarn theme={null}
yarn add @docsearch/react@4
```
```bash pnpm theme={null}
pnpm add @docsearch/react@4
```
Alternatively, use the CDN version:
```html theme={null}
```
### Basic Usage
Import the `DocSearch` component and render it in your application:
```jsx App.jsx theme={null}
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
function App() {
return (
{/* Your documentation content */}
);
}
export default App;
```
### TypeScript Support
DocSearch has full TypeScript support with type definitions included:
```tsx App.tsx theme={null}
import { DocSearch } from '@docsearch/react';
import type { DocSearchProps } from '@docsearch/react';
import '@docsearch/css';
import type { JSX } from 'react';
function App(): JSX.Element {
return (
);
}
export default App;
```
### Using a Ref
Access the DocSearch instance programmatically using a ref:
```jsx theme={null}
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 (
);
}
```
### Complete Example
Here's a complete React example with customization:
```jsx theme={null}
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
function App() {
return (
);
}
export default App;
```
## Verify It's Working
After implementing DocSearch, you should see:
A search button with the text "Search" (or your custom text) and keyboard shortcut hint (Ctrl+K or ⌘K) appears in your application.
Clicking the search button or pressing Ctrl+K (⌘K on Mac) opens the search modal.
Typing a query returns relevant results from your documentation index.
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:
```javascript theme={null}
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:
```javascript theme={null}
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:
Customize colors, fonts, and layout to match your brand
Explore all configuration options and methods
Learn about transformItems, custom components, and more
Enable AI-powered conversational search
## Troubleshooting
### Search button not appearing
Make sure you've:
1. Imported the CSS: `import '@docsearch/css';`
2. Provided a valid container selector
3. Called `docsearch()` after the DOM is ready
### No search results
Check that:
1. Your Algolia credentials are correct
2. The index name matches your DocSearch index
3. Your index has been crawled and populated
4. Your API key has search permissions
### Styles not loading
Ensure:
1. You've imported `@docsearch/css` in your entry file
2. Your bundler is configured to handle CSS imports
3. The CSS is loaded before rendering the component
### TypeScript errors
DocSearch includes TypeScript definitions. Make sure:
1. You're using `@docsearch/react@4` or `@docsearch/js@4`
2. Your `tsconfig.json` includes the node\_modules directory
3. You're importing types correctly: `import type { DocSearchProps } from '@docsearch/react';`
## Get Help
If you need assistance:
* Check the [API Reference](/api/docsearch-react) for detailed documentation
* Browse [examples on GitHub](https://github.com/algolia/docsearch/tree/main/examples)
* Visit the [DocSearch website](https://docsearch.algolia.com)
* Join the [Algolia Community](https://www.algolia.com/developers/community/)