> ## 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.
# Configuration
> Configure DocSearch with these options to customize search behavior, appearance, and functionality.
DocSearch accepts configuration options through the `DocSearchProps` interface. Pass these options to the `DocSearch` component to customize its behavior.
## Required Options
Algolia application ID used by the search client.
Public API key with search permissions for the index.
Name of the Algolia index to query.
**Deprecated:** Use `indices` property instead. This will be removed in a future version.
List of indices and optional search parameters to be used for search. Each item can be:
* A string (index name)
* A `DocSearchIndex` object with `name` and optional `searchParameters`
```typescript theme={null}
interface DocSearchIndex {
name: string;
searchParameters?: SearchParamsObject;
}
```
```tsx Simple Usage theme={null}
```
```tsx With Search Parameters theme={null}
```
## Ask AI Configuration
Configuration to enable Ask AI mode. Pass a string assistant ID or a full config object.
```typescript theme={null}
type DocSearchAskAi = {
// The assistant ID to use for the ask AI feature
assistantId: string;
// Optional: Index name for AI search (defaults to main index)
indexName?: string;
// Optional: API key for AI (defaults to main apiKey)
apiKey?: string;
// Optional: App ID for AI (defaults to main appId)
appId?: string;
// Enable suggested questions on new conversation screen
// Default: false
suggestedQuestions?: boolean;
// Search parameters for the AI feature
searchParameters?: AskAiSearchParameters;
// Experimental: Use Agent Studio as chat backend
agentStudio?: boolean;
};
type AskAiSearchParameters = {
facetFilters?: string[];
filters?: string;
attributesToRetrieve?: string[];
restrictSearchableAttributes?: string[];
distinct?: boolean | number | string;
};
```
```tsx Simple Usage theme={null}
```
```tsx Full Configuration theme={null}
```
Intercept Ask AI requests (e.g., submitting a prompt or selecting a suggested question).
Return `true` to prevent the default modal Ask AI flow (no toggle, no sendMessage). Useful to route Ask AI into a different UI (e.g., sidepanel) without flicker.
```typescript theme={null}
interface InitialAskAiMessage {
query: string;
suggestedQuestionId?: string;
messageId?: string;
}
```
## Search Customization
Placeholder text for the search input.
```tsx theme={null}
```
Additional Algolia search parameters to merge into each query.
**Deprecated:** Use `indices` property instead. This will be removed in a future version.
Maximum number of hits to display per source/group.
```tsx theme={null}
```
Hook to post-process hits before rendering. Useful for filtering, sorting, or modifying search results.
```tsx Filter Results theme={null}
{
return items.filter(item =>
!item.url.includes('/deprecated/')
);
}}
/>
```
```tsx Boost Results theme={null}
{
return items.map(item => ({
...item,
// Boost guides in search rankings
_rankingInfo: item.type === 'lvl1' &&
item.hierarchy.lvl0 === 'Guides'
? { ...item._rankingInfo, promoted: true }
: item._rankingInfo
}));
}}
/>
```
Hook to wrap or modify the Algolia search client. Useful for adding custom headers, logging, or modifying requests.
```typescript theme={null}
type DocSearchTransformClient = {
search: LiteClient['search'];
addAlgoliaAgent: LiteClient['addAlgoliaAgent'];
transporter: Pick;
};
```
```tsx Add Custom Headers theme={null}
{
searchClient.transporter.headers = {
...searchClient.transporter.headers,
'X-Custom-Header': 'value'
};
return searchClient;
}}
/>
```
```tsx Log Searches theme={null}
{
const originalSearch = searchClient.search;
searchClient.search = async (requests) => {
console.log('Search requests:', requests);
const results = await originalSearch(requests);
console.log('Search results:', results);
return results;
};
return searchClient;
}}
/>
```
## Custom Components
Custom component to render an individual hit. Supports multiple template patterns:
* HTML strings with html helper: `(props, { html }) => html\`
`}
/>
```
Custom component rendered at the bottom of the results panel. Supports the same template patterns as `hitComponent`.
```typescript theme={null}
interface ResultsFooterProps {
state: AutocompleteState;
}
```
```tsx theme={null}
(
Found {state.context.nbHits} results
)}
/>
```
## User Personalization
Disable storage and usage of recent and favorite searches.
```tsx theme={null}
```
Limit of how many recent searches should be saved and displayed.
Limit of how many recent searches should be saved and displayed when there are favorited searches.
## Navigation & Behavior
Query string to prefill when opening the modal.
```tsx theme={null}
```
Custom navigator for controlling link navigation. Useful for integrating with client-side routers.
```tsx theme={null}
```
Builds a URL to report missing results for a given query.
```tsx theme={null}
`https://github.com/myorg/docs/issues/new?title=Missing results for: ${query}`
}
/>
```
Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
```typescript theme={null}
type DocSearchModalShortcuts = {
'Ctrl/Cmd+K'?: boolean;
'/'?: boolean;
};
```
```tsx Disable Slash Shortcut theme={null}
```
```tsx Disable All Shortcuts theme={null}
```
## Theming & Display
Theme overrides applied to the modal and related components. Accepts `'dark'` or `'light'`.
See [Theme Options](/api/theme-options) for more details.
```tsx theme={null}
```
Localized strings for the button and modal UI.
See [Translations](/api/translations) for all available translation strings.
```tsx theme={null}
```
The container element where the modal should be portaled to. Defaults to `document.body`.
```tsx theme={null}
```
## Analytics
Insights client integration options to send analytics events.
```tsx theme={null}
({
...event,
eventName: 'Hits Viewed'
}));
insights.viewedObjectIDs(...events);
}
}}
/>
```
## Usage Example
```tsx Basic Configuration theme={null}
import { DocSearch } from '@docsearch/react';
function App() {
return (
);
}
```
```tsx Advanced Configuration theme={null}
import { DocSearch } from '@docsearch/react';
function App() {
return (
{
return items.filter(item =>
!item.url.includes('/deprecated/')
);
}}
navigator={{
navigate({ itemUrl }) {
router.push(itemUrl);
}
}}
translations={{
button: {
buttonText: 'Search'
}
}}
/>
);
}
```