relevantSort({
container: string | HTMLElement,
// Optional parameters
templates?: object,
cssClasses?: object,
});
Import
import { relevantSort } from "instantsearch.js/es/widgets";
Virtual indices let you 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 but can return less relevant results.
Examples
relevantSort({
container: "#relevant-sort",
});
Options
container
string | HTMLElement
required
The CSS Selector or HTMLElement
to insert the widget into.relevantSort({
container: "#relevant-sort",
});
The templates to use for the widget.relevantSort({
// ...
templates: {
// ...
},
});
The CSS classes you can override:
root
. The root element of the widget.
text
. The text element for explanation.
button
. The toggle button element.
relevantSort({
// ...
cssClasses: {
root: "MyCustomRelevantSort",
button: [
"MyCustomRelevantSort-button",
"MyCustomRelevantSort-button--subclass",
],
},
});
Templates
You can customize parts of a widget’s UI using the Templates API.
Each template includes an html
function,
which you can use as a tagged template.
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see Templating your UI.
The html
function is available in InstantSearch.js version 4.46.0 or later.
The template used for displaying the toggle button.relevantSort({
// ...
templates: {
button: "Toggle",
},
});
The template used for displaying extra information.relevantSort({
// ...
templates: {
text: "Click the button",
},
});
HTML output
<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.
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 {
isVirtualReplica,
isRelevantSorted,
canRefine,
refine,
widgetParams,
} = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
Render options
Indicates whether the index is a virtual replica.const renderRelevantSort = (renderOptions, isFirstRender) => {
const { isVirtualReplica } = renderOptions;
const container = document.querySelector("#relevant-sort");
container.innerHTML =
"This index is a " +
(isVirtualReplica ? "virtual replica" : "standard replica");
};
Indicates whether the search result is relevantly sorted out.const renderRelevantSort = (renderOptions, isFirstRender) => {
const { isRelevantSorted } = renderOptions;
const container = document.querySelector("#relevant-sort");
container.innerHTML =
"Showing " + (isRelevantSorted ? "relevant results." : "all results.");
};
Indicates if search state can be refined.const renderRelevantSort = (renderOptions, isFirstRender) => {
const { canRefine } = renderOptions;
if (!canRefine) {
document.querySelector("#relevant-sort").innerHTML = "";
return;
}
};
Sets relevancyStrictness
.const isRelevantSortedRef = { current: undefined };
const renderRelevantSort = (renderOptions, isFirstRender) => {
const { refine, isRelevantSorted } = renderOptions;
isRelevantSortedRef.current = isRelevantSorted;
const container = document.querySelector("#relevant-sort");
if (isFirstRender) {
const button = document.createElement("button");
button.setAttribute("type", "button");
button.innerText = "Toggle";
button.addEventListener("click", () => {
// `0`: show all results
// `undefined`: fall back to the value from the index config.
refine(isRelevantSortedRef.current ? 0 : undefined);
});
container.appendChild(button);
}
};
All original widget options forwarded to the render function.const renderRelevantSort = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customRelevantSort({
container: document.querySelector("#relevant-sort"),
}),
]);
First, create your custom widgets using a rendering function.
Then, instantiate them with parameters.
There are two kinds of parameters you can pass:
- Instance parameters. Predefined options that configure Algolia’s behavior.
- Custom parameters. Parameters you define to make the widget reusable and adaptable.
Inside the renderFunction
, both instance and custom parameters are accessible through connector.widgetParams
.
const customRelevantSort = connectRelevantSort(
renderRelevantSort
);
search.addWidgets([
customRelevantSort({
container,
]);
Full example
<div id="relevant-sort"></div>