nikon/docsearch
1
0
Fork 0
Code Activity Actions
docsearch/packages/website/versioned_docs/version-v4/docsearch.mdx
Paul Jankowski 596397c359
feat(docs): Document v5 beta (#2935) 
* chore(docs): v5 documentation

* Writing style clean up

* fix: website after conflicts
2026-07-30 09:47:28 -04:00

418 lines
10 KiB
Text
Raw Blame History

---
title: Getting Started with v4
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
## Introduction
DocSearch v4 provides a significant upgrade over previous versions, offering enhanced accessibility, responsiveness, and an improved search experience for your documentation. Built on [Algolia Autocomplete][1], DocSearch v4 ensures a seamless integration trusted by leading documentation sites worldwide.
## Installation
> Looking for the Composable API documentation? You can find it [here][17].
DocSearch packages are available on the [npm registry][10].
### Docusaurus users
If your docs site is powered by Docusaurus, use [`@docsearch/docusaurus-adapter`](/docs/docusaurus-adapter) for the latest DocSearch features (including new Ask AI capabilities such as sidepanel support), while keeping `@docusaurus/preset-classic`.
<Tabs
groupId="language"
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'React', value: 'react', }
]
}>
<TabItem value="js">
```bash
yarn add @docsearch/js@4
# or with npm
npm install @docsearch/js@4
```
### Without package manager
Include CSS in your website's `<head>`
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
```
And the JavaScript at the end of your `<body>`:
```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>
```
</TabItem>
<TabItem value="react">
```bash
yarn add @docsearch/react@4
# or
npm install @docsearch/react@4
```
### Without package manager
Include CSS in your website's `<head>`:
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
```
And the JavaScript at the end of your `<body>`:
```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@4"></script>
```
</TabItem>
</Tabs>
### Optimize first query performance
Enhance your users' first search experience by using `preconnect`, see [Performance optimization](#preconnect) below
## Implementation
<Tabs
groupId="language"
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'React', value: 'react', }
]
}>
<TabItem value="js">
DocSearch requires a dedicated container in your HTML
```html
<div id="docsearch"></div>
```
Initialize DocSearch by passing your container:
```js app.js
import docsearch from '@docsearch/js';
import '@docsearch/css';
docsearch({
container: '#docsearch',
appId: 'YOUR_APP_ID',
indexName: 'YOUR_INDEX_NAME',
apiKey: 'YOUR_SEARCH_API_KEY',
});
```
DocSearch generates an accessible, fully-functional search input for you automatically.
</TabItem>
<TabItem value="react">
Integrating DocSearch into your React app is straightforward:
```jsx App.js
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
function App() {
return (
<DocSearch
appId="YOUR_APP_ID"
indexName="YOUR_INDEX_NAME"
apiKey="YOUR_SEARCH_API_KEY"
/>
);
}
export default App;
```
DocSearch generates a fully accessible search input out-of-the-box.
</TabItem>
</Tabs>
### Quick Testing (without credentials)
If you'd like to test DocSearch immediately without your own credentials, use our demo configuration:
<Tabs
groupId="language"
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'React', value: 'react', }
]
}>
<TabItem value="js">
```js
docsearch({
appId: 'PMZUYBQDAK',
apiKey: '24b09689d5b4223813d9b8e48563c8f6',
indexName: 'docsearch',
askAi: 'askAIDemo',
});
```
</TabItem>
<TabItem value="react">
```jsx
<DocSearch
appId="PMZUYBQDAK"
apiKey="24b09689d5b4223813d9b8e48563c8f6"
indexName="docsearch"
askAi="askAIDemo"
/>
```
</TabItem>
</Tabs>
Or use our new dedicated [DocSearch Playground](https://community.algolia.com/docsearch-playground/)
### Using DocSearch with Ask AI
DocSearch v4 introduces support for Ask AI, Algolia's advanced, AI-powered search capability. Ask AI enhances the user experience by providing contextually relevant and intelligent responses directly from your documentation. You can also use the same `askAi` configuration object to route chat through Agent Studio.
To enable Ask AI, you can add your Algolia Assistant ID as a string, or use an object for more advanced configuration (such as specifying a different index, credentials, search parameters, or enabling Agent Studio):
<Tabs groupId="askai-format" defaultValue="string" values={[{ label: 'String', value: 'string' }, { label: 'Object', value: 'object' }]}>
<TabItem value="string">
```js
docsearch({
appId: 'YOUR_APP_ID',
indexName: 'YOUR_INDEX_NAME',
apiKey: 'YOUR_SEARCH_API_KEY',
askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});
```
</TabItem>
<TabItem value="object">
```js
docsearch({
appId: 'YOUR_APP_ID',
indexName: 'YOUR_INDEX_NAME',
apiKey: 'YOUR_SEARCH_API_KEY',
askAi: {
indexName: 'YOUR_MARKDOWN_INDEX', // Optional: use a different index for Ask AI
apiKey: 'YOUR_SEARCH_API_KEY', // Optional: use a different API key for Ask AI
appId: 'YOUR_APP_ID', // Optional: use a different App ID for Ask AI
assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
searchParameters: {
facetFilters: ['language:en', 'version:1.0.0'], // Optional: filter Ask AI context
},
suggestedQuestions: true // Optional: enable loading suggested questions on the Ask AI new conversation screen
},
});
```
</TabItem>
</Tabs>
- Use the string form for a simple setup.
- Use the object form to customize which index, credentials, or filters Ask AI uses.
- The suggested questions feature is controlled on the [Dashboard](https://dashboard.algolia.com) in the Ask AI section.
### Using Agent Studio with DocSearch
To use [Algolia Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio) as the chat backend, set `agentStudio: true` inside the `askAi` object.
```js
docsearch({
appId: 'YOUR_APP_ID',
indexName: 'YOUR_INDEX_NAME',
apiKey: 'YOUR_SEARCH_API_KEY',
askAi: {
assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
agentStudio: true,
searchParameters: {
YOUR_INDEX_NAME: {
filters: 'type:content AND language:en',
attributesToRetrieve: ['title', 'content', 'url'],
restrictSearchableAttributes: ['title', 'content'],
distinct: 'url',
},
},
},
});
```
- `agentStudio` is configured inside `askAi`, not as a top-level DocSearch prop.
- When `agentStudio: true`, `searchParameters` must be keyed by index name.
- Agent Studio search parameters support `filters`, `attributesToRetrieve`, `restrictSearchableAttributes`, and `distinct`.
### Filtering search results
#### Keyword search
If your website uses [DocSearch meta tags][13] or if you've added [custom variables to your config][14], you'll be able to use the [`facetFilters`][16] option to scope your search results to a [`facet`][15]
This is useful to limit the scope of the search to one language or one version.
<Tabs
groupId="language"
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'React', value: 'react', }
]
}>
<TabItem value="js">
```js
docsearch({
searchParameters: {
facetFilters: ['language:en', 'version:1.0.0'],
},
});
```
</TabItem>
<TabItem value="react">
```jsx
<DocSearch
searchParameters={{
facetFilters: ['language:en', 'version:1.0.0'],
}}
/>
```
</TabItem>
</Tabs>
#### Ask AI
Filtering also applies when using Ask AI. This is useful to limit the scope of the LLM's search to only relevant results.
:::info
We recommend using the `facetFilters` option when using Ask AI with multiple languages or any multi-faceted index.
:::
<Tabs
groupId="language"
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'React', value: 'react', }
]
}>
<TabItem value="js">
```js
docsearch({
askAi: {
assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
searchParameters: {
facetFilters: ['language:en', 'version:1.0.0'],
},
},
});
```
</TabItem>
<TabItem value="react">
```jsx
<DocSearch
askAi={{
assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
searchParameters: {
facetFilters: ['language:en', 'version:1.0.0'],
},
}}
/>
```
</TabItem>
</Tabs>
:::tip
You can use `facetFilters: ['type:content']` to ensure Ask AI only uses records where the `type` attribute is `content` (i.e., only records that actually have content). This is useful if your index contains records for navigation, metadata, or other non-content types.
:::
### Sending events
You can send search events to your DocSearch index by passing in the `insights` parameter when creating your DocSearch instance.
<Tabs
groupId="language"
defaultValue="js"
values={[
{ label: 'JavaScript', value: 'js', },
{ label: 'React', value: 'react', }
]
}>
<TabItem value="js">
```diff
docsearch({
// other options
+ insights: true,
});
```
</TabItem>
<TabItem value="react">
```diff
<DocSearch
// other options
+ insights={true}
/>
```
</TabItem>
</Tabs>
## Performance optimization
### Preconnect
Improve the loading speed of your initial search request by adding this snippet into your website's `<head>` section:
```html
<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />
```
This helps the browser establish a quick connection with Algolia, enhancing user experience, especially on mobile devices.
[1]: https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/
[2]: https://github.com/algolia/docsearch/
[3]: https://github.com/algolia/docsearch/tree/master
[4]: /docs/legacy/dropdown
[5]: /docs/integrations
[6]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
[7]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
[8]: https://codesandbox.io/s/docsearch-js-v3-playground-z9oxj
[9]: https://codesandbox.io/s/docsearch-react-v3-playground-619yg
[10]: https://www.npmjs.com/
[11]: /docs/api#container
[12]: /docs/api
[13]: /docs/required-configuration#introduce-global-information-as-meta-tags
[14]: /docs/record-extractor#indexing-content-for-faceting
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/
[16]: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/#facetfilters
[17]: /docs/composable-api
View git blame Copy permalink