Skip to main content

Documentation Index

Fetch the complete documentation index at: https://algolia.com/llms.txt

Use this file to discover all available pages before exploring further.

Signature
relevantSort({
  container: string | HTMLElement,
  // Optional parameters
  templates?: object,
  cssClasses?: object,
});

​
Import

import { relevantSort } from "instantsearch.js/es/widgets";

See this widget in action

Preview this widget and its behavior.

​
About this widget

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

JavaScript
relevantSort({
  container: "#relevant-sort",
});

​
Options

​
container
string | HTMLElement
required
The CSS Selector or HTMLElement to insert the widget into.
relevantSort({
  container: "#relevant-sort",
});
​
templates
object
The templates to use for the widget.
JavaScript
relevantSort({
  // ...
  templates: {
    // ...
  },
});
​
cssClasses
object
The CSS classes you can override:
  • root. The root element of the widget.
  • text. The text element for explanation.
  • button. The toggle button element.
JavaScript
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.
​
button
string | function
The template used for displaying the toggle button.
relevantSort({
  // ...
  templates: {
    button: "Toggle",
  },
});
​
text
string | function
The template used for displaying extra information.
relevantSort({
  // ...
  templates: {
    text: "Click the button",
  },
});

​
HTML output

HTML
<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:
JavaScript
// 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).
JavaScript
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

​
isVirtualReplica
boolean
Indicates whether the index is a virtual replica.
JavaScript
const renderRelevantSort = (renderOptions, isFirstRender) => {
  const { isVirtualReplica } = renderOptions;

  const container = document.querySelector("#relevant-sort");

  container.innerHTML =
    "This index is a " +
    (isVirtualReplica ? "virtual replica" : "standard replica");
};
​
isRelevantSorted
boolean
Indicates whether the search result is relevantly sorted out.
JavaScript
const renderRelevantSort = (renderOptions, isFirstRender) => {
  const { isRelevantSorted } = renderOptions;

  const container = document.querySelector("#relevant-sort");

  container.innerHTML =
    "Showing " + (isRelevantSorted ? "relevant results." : "all results.");
};
​
canRefine
boolean
required
Indicates if search state can be refined.
JavaScript
const renderRelevantSort = (renderOptions, isFirstRender) => {
  const { canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector("#relevant-sort").innerHTML = "";
    return;
  }
};
​
refine
function
Sets relevancyStrictness.
JavaScript
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);
  }
};
​
widgetParams
object
All original widget options forwarded to the render function.
JavaScript
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.
JavaScript
const customRelevantSort = connectRelevantSort(
  renderRelevantSort
);

search.addWidgets([
  customRelevantSort({
    container,
]);

​
Full example

<div id="relevant-sort"></div>
Last modified on March 23, 2026