relevantSort
relevantSort({ container: string|HTMLElement, // Optional parameters templates: object, cssClasses: object, });
1
import { relevantSort } from 'instantsearch.js/es/widgets';
About this widget
Virtual indices allow you to use Relevant sort, a sorting mechanism that favors relevancy over the attribute you’re sorting on. The relevantSort
widget displays the current search mode when searching in a virtual replica index, and allows users to switch between Relevant and regular sorting, which is more exhaustive and can return less relevant results.
Examples
1
2
3
relevantSort({
container: '#relevant-sort',
});
Options
container
|
type: string|HTMLElement
Required
The CSS Selector or |
||
Copy
|
|||
templates
|
type: object
Optional
The templates to use for the widget. |
||
Copy
|
|||
cssClasses
|
type: object
The CSS classes to override.
|
||
Copy
|
Templates
You can customize parts of the widget’s UI using the Templates API.
Every template provides an html
function you can use as a tagged template. Using html
lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.
The html
function is available starting from v4.46.0.
button
|
type: string|function
Optional
The template used for displaying the toggle button. |
||
Copy
|
|||
text
|
type: string|function
Optional
The template used for displaying extra information. |
||
Copy
|
HTML output
1
2
3
4
5
6
<div class="ais-RelevantSort my-RelevantSort">
<div class="ais-RelevantSort-text"></div>
<button type="button" class="ais-RelevantSort-button">
<span>See all results</span>
</button>
</div>
Customize the UI with connectRelevantSort
If you want to create your own UI of the relevantSort
widget, you can use connectors.
To use connectRelevantSort
, you can import it with the declaration relevant to how you installed InstantSearch.js.
1
import { connectRelevantSort } from 'instantsearch.js/es/connectors';
Then it’s a 3-step process:
// 1. Create a render function
const renderRelevantSort = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customRelevantSort = connectRelevantSort(
renderRelevantSort
);
// 3. Instantiate
search.addWidgets([
customRelevantSort({
// 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 renderRelevantSort = (renderOptions, isFirstRender) => {
const {
boolean isVirtualReplica,
boolean isRelevantSorted,
boolean canRefine,
function refine,
object widgetParams,
} = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
}
Render options
isVirtualReplica
|
type: boolean
Indicates whether the index is a virtual replica. |
||
Copy
|
|||
isRelevantSorted
|
type: boolean
Indicates whether the search result is relevantly sorted out. |
||
Copy
|
|||
canRefine
|
type: boolean
Required
Indicates if search state can be refined. |
||
Copy
|
|||
refine
|
type: function
Sets |
||
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 customRelevantSort = connectRelevantSort(
renderRelevantSort
);
search.addWidgets([
customRelevantSort({
container: string|HTMLElement
// Optional parameters
templates: object
cssClasses: object
})
]);
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
// Create a render function
const isRelevantSortedRef = { current: undefined }
const renderRelevantSort = (renderOptions, isFirstRender) => {
const {
isVirtualReplica,
isRelevantSorted,
refine,
widgetParams,
} = renderOptions;
isRelevantSortedRef.current = isRelevantSorted;
if (isFirstRender) {
const button = document.createElement('button');
button.addEventListener('click', () => {
refine(isRelevantSortedRef.current ? 0 : undefined);
});
widgetParams.container.appendChild(button);
}
const button = widgetParams.container.querySelector('button');
button.textContent =
isRelevantSortedRef.current ? 'See all results' : 'See relevant results';
};
// create custom widget
const customRelevantSort = connectRelevantSort(
renderRelevantSort
);
// instantiate custom widget
search.addWidgets([
customRelevantSort({
container: document.querySelector('#relevant-sort'),
})
]);