> ## 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.
# React Installation
> Install and configure DocSearch in React applications
DocSearch provides a native React component that integrates seamlessly with React applications. The component is built with React hooks and supports React 16.8+.
## Installation
Install the `@docsearch/react` package using your preferred package manager:
```bash npm theme={null}
npm install @docsearch/react
```
```bash yarn theme={null}
yarn add @docsearch/react
```
```bash pnpm theme={null}
pnpm add @docsearch/react
```
The package requires React >= 16.8.0 and React DOM >= 16.8.0 as peer dependencies.
### CDN Installation
For quick prototyping, you can load DocSearch from a CDN:
```html theme={null}
```
## Basic Setup
Import the `DocSearch` component and CSS styles:
```jsx theme={null}
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
```
Render the `DocSearch` component with your Algolia credentials:
```jsx theme={null}
function App() {
return (
);
}
```
Don't have your Algolia credentials yet? [Apply to DocSearch](https://docsearch.algolia.com/apply) to get started for free.
## Complete Example
Here's a complete example with typical configuration:
```jsx App.jsx theme={null}
import React from 'react';
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
function App() {
return (
{/* Your content */}
);
}
export default App;
```
## API Reference
### DocSearch Component
The main React component for rendering DocSearch.
#### Props
Your Algolia application ID.
Your Algolia Search API key (public, search-only key).
The name of your Algolia index to search.
The `indexName` prop is deprecated. Use the `indices` prop instead for multi-index support.
List of indices to search. Each item can be a string (index name) or an object with `name` and optional `searchParameters`.
```jsx theme={null}
```
Placeholder text for the search input. Defaults to "Search docs".
Additional Algolia search parameters to apply to all queries.
The `searchParameters` prop is deprecated. Use the `indices` prop with per-index parameters instead.
Maximum number of results to show per category. Defaults to 5.
Hook to transform search results before rendering.
```jsx theme={null}
{
return items.map(item => ({
...item,
url: item.url.replace('https://example.com', '')
}));
}}
/>
```
Custom component to render individual search results.
```jsx theme={null}
(
{children}
)}
/>
```
Custom component rendered at the bottom of the results panel.
```jsx theme={null}
(
Found {state.collections.length} results
)}
/>
```
Hook to wrap or modify the Algolia search client.
```jsx theme={null}
{
searchClient.addAlgoliaAgent('my-app', '1.0.0');
return searchClient;
}}
/>
```
Custom navigator for controlling link navigation. Useful for client-side routing.
```jsx theme={null}
// React Router example
import { useNavigate } from 'react-router-dom';
function SearchComponent() {
const navigate = useNavigate();
return (
);
}
```
Disable storage and display of recent and favorite searches. Defaults to `false`.
Query string to prefill when opening the search modal.
Localized strings for the button and modal UI.
```jsx theme={null}
```
Returns a URL to report missing results for a given query.
```jsx theme={null}
`https://github.com/myorg/docs/issues/new?title=Missing results for "${query}"`
}
/>
```
Algolia Insights client integration for analytics.
```jsx theme={null}
import aa from 'search-insights';
aa('init', {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_SEARCH_API_KEY'
});
```
Theme overrides for customizing the appearance.
```jsx theme={null}
```
The container element where the modal should be portaled. Defaults to `document.body`.
Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
```jsx theme={null}
```
Configuration for Ask AI mode. Pass an assistant ID string or a full configuration object.
```jsx theme={null}
```
## Using Refs
You can access DocSearch methods using a ref:
```jsx theme={null}
import React, { useRef } from 'react';
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
function App() {
const searchRef = useRef(null);
const openSearch = () => {
searchRef.current?.open();
};
const openAskAi = () => {
searchRef.current?.openAskAi({ query: 'How do I get started?' });
};
return (
);
}
```
### Ref Methods
Opens the search modal programmatically.
Closes the search modal programmatically.
Opens Ask AI mode with an optional pre-filled message.
```jsx theme={null}
searchRef.current?.openAskAi({
query: 'How do I configure search?',
messageId: 'msg_123'
});
```
Returns `true` if the modal is currently open.
## Modular Components
DocSearch also exports individual components for advanced use cases:
### DocSearchButton
The search button component without the modal:
```jsx theme={null}
import { DocSearchButton } from '@docsearch/react/button';
function CustomSearch() {
return (
{
console.log('Search button clicked');
}}
/>
);
}
```
### DocSearchModal
The search modal component without the button:
```jsx theme={null}
import { useState } from 'react';
import { DocSearchModal } from '@docsearch/react/modal';
import '@docsearch/react/style';
function CustomSearch() {
const [isOpen, setIsOpen] = useState(false);
return (
<>
{isOpen && (
setIsOpen(false)}
/>
)}
);
}
```
### useDocSearchKeyboardEvents
Hook for handling keyboard shortcuts:
```jsx theme={null}
import { useRef, useState } from 'react';
import { useDocSearchKeyboardEvents } from '@docsearch/react/useDocSearchKeyboardEvents';
function CustomSearch() {
const [isOpen, setIsOpen] = useState(false);
const buttonRef = useRef(null);
useDocSearchKeyboardEvents({
isOpen,
onOpen: () => setIsOpen(true),
onClose: () => setIsOpen(false),
searchButtonRef: buttonRef
});
return (
);
}
```
## TypeScript Support
DocSearch is written in TypeScript and includes full type definitions:
```tsx theme={null}
import type { DocSearchProps, DocSearchHit } from '@docsearch/react';
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
const searchConfig: DocSearchProps = {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
indexName: 'YOUR_INDEX_NAME',
transformItems: (items: DocSearchHit[]) => {
return items.map(item => ({
...item,
url: new URL(item.url, window.location.origin).href
}));
}
};
function App() {
return ;
}
```
## Styling
DocSearch comes with default styles. You can customize the appearance using:
### CSS Variables
```css theme={null}
:root {
--docsearch-primary-color: #5468ff;
--docsearch-text-color: #1c1e21;
--docsearch-spacing: 12px;
--docsearch-icon-stroke-width: 1.4;
--docsearch-highlight-color: var(--docsearch-primary-color);
--docsearch-muted-color: #969faf;
--docsearch-container-background: rgba(101, 108, 133, 0.8);
--docsearch-modal-background: #f5f6f7;
}
```
### Theme Prop
```jsx theme={null}
```
## Next Steps
Learn about all available configuration options
Customize the appearance of your search
Enable AI-powered search assistance
Explore the complete API documentation