hierarchicalMenu
instantsearch.widgets.hierarchicalMenu({ container: string|HTMLElement, attributes: string[], // Optional parameters limit: number, showMore: boolean, showMoreLimit: number, separator: string, rootPath: string, showParentLevel: boolean, sortBy: string[]|function, templates: object, cssClasses: object, transformItems: function, });
About this widget
The hierarchicalMenu
widget is used to create a navigation based on a hierarchy of facet attributes. It is commonly used for categories with subcategories.
Requirements
The objects to use in the hierarchical menu must follow this structure:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
{
"objectID": "321432",
"name": "lemon",
"categories.lvl0": "products",
"categories.lvl1": "products > fruits"
},
{
"objectID": "8976987",
"name": "orange",
"categories.lvl0": "products",
"categories.lvl1": "products > fruits"
}
]
It’s also possible to provide more than one path for each level:
1
2
3
4
5
6
7
8
[
{
"objectID": "321432",
"name": "lemon",
"categories.lvl0": ["products", "goods"],
"categories.lvl1": ["products > fruits", "goods > to eat"]
}
]
The attributes provided to the widget must be in attributes for faceting, either on the dashboard or using attributesForFaceting
with the API. By default, the separator is >
(with spaces) but you can use a different one by using the separator option.
Examples
1
2
3
4
5
6
7
8
9
instantsearch.widgets.hierarchicalMenu({
container: '#hierarchical-menu',
attributes: [
'hierarchicalCategories.lvl0',
'hierarchicalCategories.lvl1',
'hierarchicalCategories.lvl2',
'hierarchicalCategories.lvl3',
],
});
Options
container
|
type: string|HTMLElement
Required
The CSS Selector or |
||
Copy
|
|||
attributes
|
type: string[]
Required
The name of the attributes to generate the menu with. |
||
Copy
|
|||
limit
|
type: number
default: 10
Optional
How many facet values to retrieve. When you enable the showMore feature, this is the number of facet values to display before clicking the “Show more” button. |
||
Copy
|
|||
showMore
|
type: boolean
default: false
Optional
Whether to display a button that expands the number of items. |
||
Copy
|
|||
showMoreLimit
|
type: number
Optional
The maximum number of displayed items (only used when showMore is set to |
||
Copy
|
|||
separator
|
type: string
default: >
Optional
The level separator used in the records. |
||
Copy
|
|||
rootPath
|
type: string
default: null
Optional
The prefix path to use if the first level is not the root level. |
||
Copy
|
|||
showParentLevel
|
type: boolean
default: true
Optional
Whether to show the siblings of the selected parent level of the current refined value. |
||
Copy
|
|||
sortBy
|
type: string[]|function
default: Uses facetOrdering if set, ["name:asc"]
Optional
How to sort refinements. Must be one or more of the following strings:
It’s also possible to give a function, which receives items two by two, like JavaScript’s |
||
Copy
|
|||
templates
|
type: object
Optional
The templates to use for the widget. |
||
Copy
|
|||
cssClasses
|
type: object
default: {}
Optional
The CSS classes to override.
|
||
Copy
|
|||
transformItems
|
type: function
default: items => items
Optional
Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items. In addition, the full |
||
Copy
|
Templates
item
|
type: string|function
Optional
The template for each item. It exposes:
|
||
Copy
|
|||
showMoreText
|
type: string|function
Optional
The template for the “Show more” button text. It exposes:
|
||
Copy
|
HTML output
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
30
31
<div class="ais-HierarchicalMenu">
<ul class="ais-HierarchicalMenu-list ais-HierarchicalMenu-list--lvl0">
<li class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--parent ais-HierarchicalMenu-item--selected">
<a class="ais-HierarchicalMenu-link" href="#">
<span class="ais-HierarchicalMenu-label">Appliances</span>
<span class="ais-HierarchicalMenu-count">4,306</span>
</a>
<ul class="ais-HierarchicalMenu-list ais-HierarchicalMenu-list--child ais-HierarchicalMenu-list--lvl1">
<li class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--parent">
<a class="ais-HierarchicalMenu-link" href="#">
<span class="ais-HierarchicalMenu-label">Dishwashers</span>
<span class="ais-HierarchicalMenu-count">181</span>
</a>
</li>
<li class="ais-HierarchicalMenu-item">
<a class="ais-HierarchicalMenu-link" href="#">
<span class="ais-HierarchicalMenu-label">Fans</span>
<span class="ais-HierarchicalMenu-count">91</span>
</a>
</li>
</ul>
</li>
<li class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--parent">
<a class="ais-HierarchicalMenu-link" href="#">
<span class="ais-HierarchicalMenu-label">Audio</span>
<span class="ais-HierarchicalMenu-count">1,570</span>
</a>
</li>
</ul>
<button class="ais-HierarchicalMenu-showMore">Show more</button>
</div>
Customize the UI with connectHierarchicalMenu
If you want to create your own UI of the hierarchicalMenu
widget, you can use connectors.
It’s a 3-step process:
// 1. Create a render function
const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customHierarchicalMenu = instantsearch.connectors.connectHierarchicalMenu(
renderHierarchicalMenu
);
// 3. Instantiate
search.addWidgets([
customHierarchicalMenu({
// instance params
})
]);
Create a render function
This rendering function is called before the first search (init
lifecycle step)
and each time results come back from Algolia (render
lifecycle step).
const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
const {
object[] items,
boolean isShowingMore,
boolean canToggleShowMore,
boolean canRefine,
function refine,
function sendEvent,
function toggleShowMore,
function createURL,
object widgetParams,
} = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
}
If SEO is critical to your search page, your custom HTML markup needs to be parsable:
- use plain
<a>
tags withhref
attributes for search engines bots to follow them, - use semantic markup with structured data when relevant, and test it.
Refer to our SEO checklist for building SEO-ready search experiences.
Rendering options
items
|
type: object[]
The list of available items, with each item:
|
||
Copy
|
|||
isShowingMore
|
type: boolean
Whether the list is expanded. |
||
Copy
|
|||
canToggleShowMore
|
type: boolean
Whether the “Show more” button can be clicked. |
||
Copy
|
|||
canRefine
|
type: boolean
Required
Indicates if search state can be refined. |
||
Copy
|
|||
refine
|
type: function
Sets the path of the hierarchical filter and triggers a new search. |
||
Copy
|
|||
sendEvent
|
type: (eventType, facetValue) => void
The function to send
|
||
Copy
|
|||
toggleShowMore
|
type: function
Toggles the number of displayed values between |
||
Copy
|
|||
createURL
|
type: function
Generates a URL for the next state. |
||
Copy
|
|||
widgetParams
|
type: object
All original widget options forwarded to the render function. |
||
Copy
|
Create and instantiate the custom widget
We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:
- Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
- Your own parameters: to make the custom widget generic.
Both instance and custom parameters are available in connector.widgetParams
, inside the renderFunction
.
const customHierarchicalMenu = instantsearch.connectors.connectHierarchicalMenu(
renderHierarchicalMenu
);
search.addWidgets([
customHierarchicalMenu({
attributes: string[],
// Optional parameters
limit: number,
showMoreLimit: number,
separator: string,
rootPath: string,
showParentLevel: boolean,
sortBy: string[]|function,
transformItems: function,
})
]);
Instance options
attributes
|
type: string[]
Required
The name of the attributes to generate the menu with. |
||
Copy
|
|||
limit
|
type: number
default: 10
Optional
How many facet values to retrieve. When isShowingMore is |
||
Copy
|
|||
showMoreLimit
|
type: number
Optional
The maximum number of displayed items (only used when the |
||
Copy
|
|||
separator
|
type: string
default: >
Optional
The level separator used in the records. |
||
Copy
|
|||
rootPath
|
type: string
default: null
Optional
The prefix path to use if the first level is not the root level. |
||
Copy
|
|||
showParentLevel
|
type: boolean
default: true
Optional
Whether to show the siblings of the selected parent level of the current refined value. |
||
Copy
|
|||
sortBy
|
type: string[]|function
default: Uses facetOrdering if set, ["name:asc"]
Optional
How to sort refinements. Must be one or more of the following strings:
It’s also possible to give a function, which receives items two by two, like JavaScript’s If |
||
Copy
|
|||
transformItems
|
type: function
default: items => items
Optional
Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items. In addition, the full |
||
Copy
|
Full example
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
// Create the render function
const renderList = ({ items, createURL }) => `
<ul>
${items
.map(
item => `
<li>
<a
href="${createURL(item.value)}"
data-value="${item.value}"
style="font-weight: ${item.isRefined ? 'bold' : ''}"
>
${item.label} (${item.count})
</a>
${item.data ? renderList({ items: item.data, createURL }) : ''}
</li>
`
)
.join('')}
</ul>
`;
const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
const {
items,
isShowingMore,
refine,
toggleShowMore,
createURL,
widgetParams,
} = renderOptions;
if (isFirstRender) {
const list = document.createElement('div');
const button = document.createElement('button');
button.addEventListener('click', () => {
toggleShowMore();
});
widgetParams.container.appendChild(list);
widgetParams.container.appendChild(button);
}
const children = renderList({ items, createURL });
widgetParams.container.querySelector('div').innerHTML = children;
widgetParams.container.querySelector('button').textContent = isShowingMore
? 'Show less'
: 'Show more';
[...widgetParams.container.querySelectorAll('a')].forEach(element => {
element.addEventListener('click', event => {
event.preventDefault();
refine(event.target.dataset.value);
});
});
};
// Create the custom widget
const customHierarchicalMenu = instantsearch.connectors.connectHierarchicalMenu(
renderHierarchicalMenu
);
// Instantiate the custom widget
search.addWidgets([
customHierarchicalMenu({
container: document.querySelector('#hierarchical-menu'),
attributes: [
'hierarchicalCategories.lvl0',
'hierarchicalCategories.lvl1',
'hierarchicalCategories.lvl2',
'hierarchicalCategories.lvl3',
],
limit: 5,
showMoreLimit: 10,
})
]);