Displaying Items with Templates
Once you’ve set up your data sources, you need to define how they display in your autocomplete experience. It encompasses the structure for each item and the way they look.
Autocomplete provides a Templates API to let you fully customize the render of each item.
Rendering each item
The rendering system of Autocomplete uses an agnostic virtual DOM implementation. You can return anything from each template as long as they’re valid virtual DOM elements (VNodes).
For example, templates can return a string:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { autocomplete } from '@algolia/autocomplete-js';
autocomplete({
// ...
getSources() {
return [
{
// ...
templates: {
item({ item }) {
return `Result: ${item.name}`;
},
},
},
];
},
});
Or a Preact component:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/** @jsx h */
import { h } from 'preact';
import { autocomplete } from '@algolia/autocomplete-js';
autocomplete({
// ...
getSources() {
return [
{
// ...
templates: {
item({ item }) {
return <div>{item.name}</div>;
},
},
},
];
},
});
Autocomplete uses Preact 10 to render templates by default. It isn’t compatible with earlier versions.
Returning HTML
Native HTML elements aren’t valid VNodes, which means you can’t return a template string that contains HTML, or an HTML element. But if you’re not using a virtual DOM implementation in your app, there are still two ways you can return HTML.
Using createElement
Each template function provides access to createElement and Fragment to create VNodes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { autocomplete } from '@algolia/autocomplete-js';
autocomplete({
// ...
getSources() {
return [
{
// ...
templates: {
item({ item, createElement, Fragment }) {
return createElement(Fragment, {}, item.name);
},
},
},
];
},
});
You can also leverage dangerouslySetInnerHTML if you need to provide more complex HTML without having to create nested VNodes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { autocomplete } from '@algolia/autocomplete-js';
autocomplete({
// ...
getSources() {
return [
{
// ...
templates: {
item({ item, createElement }) {
return createElement('div', {
dangerouslySetInnerHTML: {
__html: `<div>
<img
src="${item.image}"
alt="${item.name}"
/>
</div>
<div>
${item.name}
</div>`,
},
});
},
},
},
];
},
});
By default, createElement and Fragment default to Preact’s preact.createElement (or h) and preact.Fragment. You can customize these and provide the virtual DOM implementation you prefer.
Using the htm library
If you’re not using a transpiler to build your app, you can still use Autocomplete with the
htm
library, which lets you use a JSX-like syntax directly in the browser.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { html } from 'htm/preact';
import { autocomplete } from '@algolia/autocomplete-js';
autocomplete({
// ...
getSources() {
return [
{
// ...
templates: {
item({ item }) {
return html`<div>${item.name}</div>`;
},
},
},
];
},
});
Rendering a header and footer
In addition to rendering items, you can customize what to display before and after the list of items using the header and footer templates.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
autocomplete({
// ...
getSources({ query }) {
return [
{
// ...
templates: {
header() {
return 'Suggestions';
},
item({ item }) {
return `Result: ${item.name}`;
},
footer() {
return 'Footer';
},
},
},
];
},
});
Rendering a no results state
When there are no results, you might want to display a message to inform users or let them know what to do next. You can do this with the noResults template.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
autocomplete({
// ...
getSources({ query }) {
return [
{
// ...
templates: {
// ...
noResults() {
return 'No results.';
},
},
},
];
},
});
Styling items
Since you’re fully controlling the rendered HTML, you can style it the way you want or use any class-based CSS library.
For example, if you’re using Bootstrap:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/** @jsx h */
import { h } from 'preact';
import { autocomplete } from '@algolia/autocomplete-js';
import 'https://cdn.jsdelivr.net/npm/bootstrap@latest/dist/css/bootstrap.min.css';
autocomplete({
// ...
getSources() {
return [
{
// ...
templates: {
item({ item }) {
return <div class="list-group-item-action">{item.name}</div>;
},
},
},
];
},
});
Or Tailwind CSS:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
/** @jsx h */
import { h } from 'preact';
import { autocomplete } from '@algolia/autocomplete-js';
import 'https://unpkg.com/tailwindcss@latest/dist/tailwind.min.css';
autocomplete({
// ...
getSources() {
return [
{
// ...
templates: {
item({ item }) {
return (
<div class="py-2 px-4 rounded-sm border border-gray-200">
{item.name}
</div>
);
},
},
},
];
},
});
Reference
templates
|
type: AutocompleteTemplates
A set of templates to customize how items are displayed. You can also provide templates for header and footer elements around the list of items. You must define See template for what to return. |
template ➔ template
header
|
type: (params: { state: AutocompleteState<TItem>, source: AutocompleteSource<TItem>, items: TItem[], createElement: Pragma, Fragment: PragmaFrag }) => VNode | string
A function that returns the template for the header (before the list of items). |
item
|
type: (params: { item: TItem, state: AutocompleteState<TItem>, createElement: Pragma, Fragment: PragmaFrag }) => VNode | string
A function that returns the template for each item of the source. |
footer
|
type: (params: { state: AutocompleteState<TItem>, source: AutocompleteSource<TItem>, items: TItem[], createElement: Pragma, Fragment: PragmaFrag }) => VNode | string
A function that returns the template for the footer (after the list of items). |
noResults
|
type: (params: { state: AutocompleteState<TItem>, source: AutocompleteSource<TItem>, createElement: Pragma, Fragment: PragmaFrag }) => VNode | string
A function that returns the template for when there are no items. |
