relevantSort

Signature

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

Import

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

const { relevantSort } = instantsearch.widgets;
// or directly use instantsearch.widgets.relevantSort()

See this widget in action

Preview this widget and its behavior.

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",
});

relevantSort({
  container: document.querySelector("#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",
  },
});

relevantSort({
  // ...
  templates: {
    button({ isRelevantSorted }) {
      return isRelevantSorted ? "See all results" : "See relevant results";
    },
  },
});

text

string | function

The template used for displaying extra information.

relevantSort({
  // ...
  templates: {
    text: "Click the button",
  },
});

searchBox({
  // ...
  templates: {
    text({ isRelevantSorted }) {
      return (
        "Click the button to " +
        (isRelevantSorted ? "see all results." : "see relevant results.")
      );
    },
  },
});

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";

const { connectRelevantSort } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectRelevantSort()

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);
  }
};

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"),
  }),
]);

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>

// 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"),
  }),
]);

InstantSearch.js

Import

See this widget in action

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectRelevantSort`

Create a render function

Render options

Create and instantiate the custom widget

Full example

​Import

See this widget in action

​About this widget

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectRelevantSort

​Create a render function

​Render options

​Create and instantiate the custom widget

​Full example

Import

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectRelevantSort`

Create a render function

Render options

Create and instantiate the custom widget

Full example