265 lines
6 KiB
Text
265 lines
6 KiB
Text
---
|
||
title: DocSearch v3
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
:::info
|
||
|
||
The following content is for **[DocSearch v3][2]**. If you are using **[DocSearch v2][3]**, see the **[legacy][4]** documentation.
|
||
|
||
:::
|
||
|
||
## Introduction
|
||
|
||
DocSearch v3 is built on top of the latest version of [Algolia Autocomplete][1], which provides better accessibility, increased responsiveness, themability, a better built-in design, and customizability under low-network conditions.
|
||
|
||
This version has been rewritten in React, and now exposes React components. The vanilla JavaScript version is based on the React version with an alias to Preact.
|
||
|
||
### Stable version
|
||
|
||
With the recent release of the stable version of [Algolia Autocomplete][1], and the huge adoption of DocSearch v3, we will start working on a stable release!
|
||
|
||
Thanks to all the Alpha testers, and to [all the integrations][5] who already support it!
|
||
|
||
## Installation
|
||
|
||
DocSearch packages are available on the [npm][10] registry.
|
||
|
||
<Tabs
|
||
groupId="language"
|
||
defaultValue="js"
|
||
values={[
|
||
{ label: 'JavaScript', value: 'js', },
|
||
{ label: 'React', value: 'react', }
|
||
]
|
||
}>
|
||
<TabItem value="js">
|
||
|
||
```bash
|
||
yarn add @docsearch/js@alpha
|
||
# or
|
||
npm install @docsearch/js@alpha
|
||
```
|
||
|
||
### Without package manager
|
||
|
||
If you don't want to use a package manger, you can add the CSS to the `<head>` of your website:
|
||
|
||
```html
|
||
<link
|
||
rel="stylesheet"
|
||
href="https://cdn.jsdelivr.net/npm/@docsearch/css@alpha"
|
||
/>
|
||
```
|
||
|
||
And the JavaScript at the end of your `<body>`:
|
||
|
||
```html
|
||
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@alpha"></script>
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem value="react">
|
||
|
||
```bash
|
||
yarn add @docsearch/react@alpha
|
||
# or
|
||
npm install @docsearch/react@alpha
|
||
```
|
||
|
||
### Without package manager
|
||
|
||
If you don't want to use a package manger, you can add the CSS to the `<head>` of your website:
|
||
|
||
```html
|
||
<link
|
||
rel="stylesheet"
|
||
href="https://cdn.jsdelivr.net/npm/@docsearch/css@alpha"
|
||
/>
|
||
```
|
||
|
||
And the JavaScript at the end of your `<body>`:
|
||
|
||
```html
|
||
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@alpha"></script>
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
### Improve first query speed
|
||
|
||
You can hint the browser to improve the speed of the first query by adding a `preconnect`, see [#preconnect](#preconnect)
|
||
|
||
## Get started
|
||
|
||
<Tabs
|
||
groupId="language"
|
||
defaultValue="js"
|
||
values={[
|
||
{ label: 'JavaScript', value: 'js', },
|
||
{ label: 'React', value: 'react', }
|
||
]
|
||
}>
|
||
<TabItem value="js">
|
||
|
||
To get started, you need a [`container`][11] for your DocSearch component to go in. If you don’t have one already, you can insert one into your markup:
|
||
|
||
```html
|
||
<div id="docsearch"></div>
|
||
```
|
||
|
||
Then, insert DocSearch into it by calling the [`docsearch`][12] function and providing the container. It can be a [CSS selector][6] or an [Element][7].
|
||
|
||
Make sure to provide a [`container`][11] (for example, a `div`), not an `input`. DocSearch generates a fully accessible search box for you.
|
||
|
||
```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',
|
||
});
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="react">
|
||
|
||
DocSearch generates a fully accessible search box for you.
|
||
|
||
```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;
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
### Testing
|
||
|
||
If you're eager to test DocSearch v3 and can't wait to receive your credentails, you can use ours!
|
||
|
||
<Tabs
|
||
groupId="language"
|
||
defaultValue="js"
|
||
values={[
|
||
{ label: 'JavaScript', value: 'js', },
|
||
{ label: 'React', value: 'react', }
|
||
]
|
||
}>
|
||
<TabItem value="js">
|
||
|
||
```js
|
||
docsearch({
|
||
appId: 'R2IYF7ETH7',
|
||
apiKey: '599cec31baffa4868cae4e79f180729b',
|
||
indexName: 'docsearch',
|
||
});
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
<TabItem value="react">
|
||
|
||
```jsx
|
||
<DocSearch
|
||
appId="R2IYF7ETH7"
|
||
apiKey="599cec31baffa4868cae4e79f180729b"
|
||
indexName="docsearch"
|
||
/>
|
||
```
|
||
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
### Filtering your search
|
||
|
||
If your website supports [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>
|
||
|
||
## Performance optimization
|
||
|
||
### Preconnect
|
||
|
||
By adding this snippet to the `head` of your website, you can hint the browser that the website will load data from Algolia, and allows it to preconnect to the DocSearch cluster. It makes the first query faster, especially on mobile.
|
||
|
||
```html
|
||
<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />
|
||
```
|
||
|
||
[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#with-custom-variables
|
||
[16]: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/#facetfilters
|
||
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/
|