Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(createQuerySuggestionsPlugin): rewrite docs #468

Merged
merged 6 commits into from
Mar 4, 2021
Merged

docs(createQuerySuggestionsPlugin): rewrite docs #468

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
afa4731
docs(createQuerySuggestionsPlugin): rewrite docs
sarahdayan Feb 25, 2021
422078e
fix(createQuerySuggestionsPlugin): fix name
sarahdayan Feb 25, 2021
99186af
fix: apply suggestions from code review
sarahdayan Feb 26, 2021
4d429df
docs(createQuerySuggestionsPlugin): document new parameters
sarahdayan Feb 26, 2021
f1309f3
fix: apply suggestions from code review
sarahdayan Mar 1, 2021
958825b
docs(createQuerySuggestionsPlugin): clarify description
sarahdayan Mar 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 76 additions & 13 deletions packages/website/docs/createQuerySuggestionsPlugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,35 @@
id: createQuerySuggestionsPlugin
---

The Query Suggestions plugin adds [Algolia Query Suggestions](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js/) to your autocomplete.

## Installation

First, you need to install the plugin.

```bash
yarn add @algolia/autocomplete-plugin-query-suggestions@alpha
# or
npm install @algolia/autocomplete-plugin-query-suggestions@alpha
```

Then import it in your project:

```js
import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
```

If you don't use a package manager, you can use a standalone endpoint:

```html
<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-query-suggestions@alpha"></script>
```

## Example

```ts
This example uses the plugin within [`autocomplete-js`](autocomplete-js), along with the [`algoliasearch`](https://www.npmjs.com/package/algoliasearch) API client.

```js
import algoliasearch from 'algoliasearch/lite';
import { autocomplete } from '@algolia/autocomplete-js';
import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
Expand All @@ -24,9 +50,9 @@ autocomplete({
});
```

With [Recent Searches](createLocalStorageRecentSearchesPlugin):
You can combine this plugin with the [Recent Searches](createLocalStorageRecentSearchesPlugin) plugin to leverage the empty screen with recent and popular queries.

```ts
```js
import algoliasearch from 'algoliasearch/lite';
import { autocomplete } from '@algolia/autocomplete-js';
import { createLocalStorageRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';
Expand Down Expand Up @@ -54,35 +80,39 @@ autocomplete({
});
```

## Import
To see it in action, check [this demo on CodeSandbox](https://fzb4m.csb.app/).

```ts
import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
```

## Params
## Parameters

### `searchClient`

> `SearchClient` | required

The initialized Algolia search client.

### `indexName`

> `string` | required

The index name.

### `getSearchParams`

> [`() => SearchParameters`](https://www.algolia.com/doc/api-reference/search-api-parameters/)
> `(params: { state: AutocompleteState }) => SearchParameters`

A function returning [Algolia search parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/).

### `transformSource`

> `(params: { source: AutocompleteSource, onTapAhead: () => void })`

#### Example
A function to transform the provided source.

#### Examples

Keeping the panel open on select:

```tsx
```jsx
const querySuggestionsPlugin = createQuerySuggestionsPlugin({
searchClient,
indexName: 'instant_search_demo_query_suggestions',
Expand All @@ -99,7 +129,7 @@ const querySuggestionsPlugin = createQuerySuggestionsPlugin({

Opening a link:

```tsx
```jsx
const querySuggestionsPlugin = createQuerySuggestionsPlugin({
searchClient,
indexName: 'instant_search_demo_query_suggestions',
Expand Down Expand Up @@ -127,3 +157,36 @@ const querySuggestionsPlugin = createQuerySuggestionsPlugin({
},
});
```

### `categoryAttribute`

> `string | string[]`

The attribute or attribute path to display categories for.

#### Example

```js
const querySuggestionsPlugin = createQuerySuggestionsPlugin({
searchClient,
indexName: 'instant_search_demo_query_suggestions',
categoryAttribute: [
'instant_search',
'facets',
'exact_matches',
'hierarchicalCategories.lvl0',
],
});
```

### `categoriesLimit`

> `number`
sarahdayan marked this conversation as resolved.
Show resolved Hide resolved

The number of items to display categories for.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wrote this description myself quickly but not sure it's very comprehensible. Wdyt?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you quickly describe it to make sure it's clear to me?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(With categoriesPerItem: 2)

categoriesLimit: 1

image

categoriesLimit: 3

image

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it! It's how many items get categories. I'm wondering if the name of the parameter is optimal though. Now that I know what it is, categoriesLimit still doesn't convey that idea. Have you thought of something more descriptive like itemsWithCategories? It doesn't convey as much that it expects a number but it's clearer.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I'm not convinced by the name either.

How about those?

  • numberOfItemsWithCategories
  • numberOfCategoriesPerItem

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find numberOf superfluous, the type conveys this information already.

  • itemsWithCategories
  • categoriesPerItem

This is simpler.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK—I'll take care of that in another PR.


### `categoriesPerItem`

> `number`
sarahdayan marked this conversation as resolved.
Show resolved Hide resolved

The number of categories to display per item.