> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# relevantSort
> Lets users switch between search modes, exhaustive or relevant sorting.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```ts Signature theme={"system"}
relevantSort({
container: string | HTMLElement,
// Optional parameters
templates?: object,
cssClasses?: object,
});
```
## Import
```js Package manager theme={"system"}
import { relevantSort } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { relevantSort } = instantsearch.widgets;
// or directly use instantsearch.widgets.relevantSort()
```
Preview this widget and its behavior.
## About this widget
Virtual indices let you use [relevant sort](/doc/guides/managing-results/refine-results/sorting/in-depth/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
```js JavaScript icon=code theme={"system"}
relevantSort({
container: "#relevant-sort",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
relevantSort({
container: "#relevant-sort",
});
```
```js HTMLElement theme={"system"}
relevantSort({
container: document.querySelector("#relevant-sort"),
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
relevantSort({
// ...
templates: {
// ...
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `root`. The root element of the widget.
* `text`. The text element for explanation.
* `button`. The toggle button element.
```js JavaScript icon=code theme={"system"}
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#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.
```js string theme={"system"}
relevantSort({
// ...
templates: {
button: "Toggle",
},
});
```
```js function theme={"system"}
relevantSort({
// ...
templates: {
button({ isRelevantSorted }) {
return isRelevantSorted ? "See all results" : "See relevant results";
},
},
});
```
The template used for displaying extra information.
```js string theme={"system"}
relevantSort({
// ...
templates: {
text: "Click the button",
},
});
```
```js function theme={"system"}
searchBox({
// ...
templates: {
text({ isRelevantSorted }) {
return (
"Click the button to " +
(isRelevantSorted ? "see all results." : "see relevant results.")
);
},
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## 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.
```js Package manager theme={"system"}
import { connectRelevantSort } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectRelevantSort } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectRelevantSort()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 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).
```js JavaScript icon=code theme={"system"}
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.
```js JavaScript icon=code theme={"system"}
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.
```js JavaScript icon=code theme={"system"}
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.
```js JavaScript icon=code theme={"system"}
const renderRelevantSort = (renderOptions, isFirstRender) => {
const { canRefine } = renderOptions;
if (!canRefine) {
document.querySelector("#relevant-sort").innerHTML = "";
return;
}
};
```
Sets `relevancyStrictness`.
```js JavaScript icon=code theme={"system"}
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.
```js JavaScript icon=code theme={"system"}
const renderRelevantSort = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customRelevantSort({
container: document.querySelector("#relevant-sort"),
}),
]);
```
### Create and instantiate the custom widget
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`.
```js JavaScript icon=code theme={"system"}
const customRelevantSort = connectRelevantSort(
renderRelevantSort
);
search.addWidgets([
customRelevantSort({
container,
]);
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// 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"),
}),
]);
```