> ## 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.

```ts Signature theme={"system"}
relevantSort({
  container: string | HTMLElement,
  // Optional parameters
  templates?: object,
  cssClasses?: object,
});
```

## Import

<CodeGroup>
  ```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()
  ```
</CodeGroup>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/?path=/story/sorting-relevantsort--default" horizontal>
  Preview this widget and its behavior.
</Card>

## 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

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    relevantSort({
      container: "#relevant-sort",
    });
    ```

    ```js HTMLElement theme={"system"}
    relevantSort({
      container: document.querySelector("#relevant-sort"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  relevantSort({
    // ...
    templates: {
      // ...
    },
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object">
  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",
      ],
    },
  });
  ```
</ParamField>

## 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).

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="button" type="string | function">
  The template used for displaying the toggle button.

  <CodeGroup>
    ```js string theme={"system"}
    relevantSort({
      // ...
      templates: {
        button: "Toggle",
      },
    });
    ```

    ```js function theme={"system"}
    relevantSort({
      // ...
      templates: {
        button({ isRelevantSorted }) {
          return isRelevantSorted ? "See all results" : "See relevant results";
        },
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="text" type="string | function">
  The template used for displaying extra information.

  <CodeGroup>
    ```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.")
          );
        },
      },
    });
    ```
  </CodeGroup>
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<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.

<CodeGroup>
  ```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()
  ```
</CodeGroup>

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

<ParamField body="isVirtualReplica" type="boolean">
  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");
  };
  ```
</ParamField>

<ParamField body="isRelevantSorted" type="boolean">
  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.");
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean" required>
  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;
    }
  };
  ```
</ParamField>

<ParamField body="refine" type="function">
  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);
    }
  };
  ```
</ParamField>

<ParamField body="widgetParams" type="object">
  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"),
    }),
  ]);
  ```
</ParamField>

### 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

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="relevant-sort"></div>
  ```

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