> ## 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.
# JavaScript Installation
> Install and configure DocSearch in vanilla JavaScript applications
DocSearch provides a standalone JavaScript package that works in any web application without requiring a framework. The package internally uses Preact for rendering while exposing a simple vanilla JS API.
## Installation
Install the `@docsearch/js` package using your preferred package manager:
```bash npm theme={null}
npm install @docsearch/js
```
```bash yarn theme={null}
yarn add @docsearch/js
```
```bash pnpm theme={null}
pnpm add @docsearch/js
```
### CDN Installation
If you prefer not to use a package manager, you can load DocSearch directly from a CDN:
```html theme={null}
```
## Basic Setup
Import the `docsearch` function and CSS styles in your application:
```javascript theme={null}
import docsearch from '@docsearch/js';
import '@docsearch/css';
```
Add a container element to your HTML where DocSearch will be rendered. DocSearch generates a fully accessible search box for you, so use a container element (like a `div`), not an `input`:
```html theme={null}
```
Call the `docsearch()` function with your configuration. You can pass either a CSS selector string or an HTML element:
```javascript theme={null}
const search = docsearch({
container: '#docsearch',
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
indexName: 'YOUR_INDEX_NAME',
});
```
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 working example:
```html index.html theme={null}
DocSearch Example
```
## API Reference
### docsearch(props)
The main function that initializes DocSearch and returns a control instance.
#### Parameters
The container for your DocSearch component. Can be a CSS selector string or an HTMLElement.
Your Algolia application ID.
Your Algolia Search API key (public, search-only key).
The name of your Algolia index to search.
Placeholder text for the search input. Defaults to "Search docs".
Additional Algolia search parameters to apply to all queries.
```javascript theme={null}
searchParameters: {
hitsPerPage: 10,
facetFilters: ['version:1.0']
}
```
Hook to transform search results before rendering.
```javascript theme={null}
transformItems: (items) => {
return items.map(item => ({
...item,
url: item.url.replace('https://example.com', '')
}));
}
```
Custom component to render individual search results. Supports JSX, HTML strings with the `html` helper, or function-based templates.
```javascript theme={null}
hitComponent: ({ hit, children }, { html }) => {
return html`${children}`;
}
```
Custom component rendered at the bottom of the results panel.
```javascript theme={null}
resultsFooterComponent: ({ state }, { html }) => {
return html``;
}
```
Hook to wrap or modify the Algolia search client.
```javascript theme={null}
transformSearchClient: (searchClient) => {
searchClient.addAlgoliaAgent('my-app', '1.0.0');
return searchClient;
}
```
Maximum number of results to show per category. Defaults to 5.
Disable storage and display of recent and favorite searches. Defaults to `false`.
Query string to prefill when opening the search modal.
#### Return Value
The `docsearch()` function returns a `DocSearchInstance` object with the following methods:
Returns `true` once the component is mounted and ready.
Returns `true` if the modal is currently open.
Opens the search modal programmatically.
Closes the search modal programmatically.
Opens Ask AI mode in the modal.
```javascript theme={null}
search.openAskAi({ query: 'How do I get started?' });
```
Unmounts the DocSearch component and cleans up resources.
## Programmatic Control
You can control DocSearch programmatically using the returned instance:
```javascript theme={null}
const search = docsearch({
container: '#docsearch',
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
indexName: 'YOUR_INDEX_NAME',
onReady: () => {
console.log('DocSearch is ready!');
},
onOpen: () => {
console.log('Search modal opened');
},
onClose: () => {
console.log('Search modal closed');
},
});
// Open the search modal programmatically
document.getElementById('custom-search-button').addEventListener('click', () => {
search.open();
});
// Check if modal is open
console.log(search.isOpen); // true or false
// Open Ask AI with a pre-filled message
search.openAskAi({ query: 'How do I configure search?' });
// Clean up when done
search.destroy();
```
## Lifecycle Callbacks
DocSearch supports lifecycle callbacks to hook into important events:
```javascript theme={null}
docsearch({
container: '#docsearch',
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_SEARCH_API_KEY',
indexName: 'YOUR_INDEX_NAME',
// Called when DocSearch is mounted and ready
onReady: () => {
console.log('DocSearch mounted');
},
// Called when the modal opens
onOpen: () => {
console.log('Modal opened');
},
// Called when the modal closes
onClose: () => {
console.log('Modal closed');
},
});
```
## Styling
DocSearch comes with default styles via `@docsearch/css`. You can customize the appearance by:
1. **CSS Variables**: Override DocSearch's CSS custom properties
2. **Custom Classes**: Target DocSearch's class names with your own CSS
3. **Theme Object**: Pass a theme configuration (see React documentation)
```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;
}
```
## Next Steps
Learn about all available configuration options
Customize the appearance of your search
Enable AI-powered search assistance
Explore the complete API documentation