UI libraries / InstantSearch.js / Widgets

relevantSort

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

import { relevantSort } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget

Virtual indices allow you to 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 and can return less relevant results.

Examples

Copy 
1
2
3

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

Options

Parameter Description
container
type: string|HTMLElement
Required

The CSS Selector or HTMLElement to insert the widget into.
Copy 
1
2
3

relevantSort({
  container: '#relevant-sort',
});
templates
type: object
Optional

The templates to use for the widget.
Copy 
1
2
3
4
5
6

relevantSort({
  // ...
  templates: {
    // ...
  },
});
cssClasses
type: 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.
Copy 
1
2
3
4
5
6
7
8
9
10

relevantSort({
  // ...
  cssClasses: {
    root: 'MyCustomRelevantSort',
    button: [
      'MyCustomRelevantSort-button',
      'MyCustomRelevantSort-button--subclass',
    ],
  },
});

Templates

You can customize parts of the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

Parameter Description
button
type: string|function
Optional

The template used for displaying the toggle button.
Copy 
1
2
3
4
5
6

relevantSort({
  // ...
  templates: {
    button: 'Toggle',
  },
});
text
type: string|function
Optional

The template used for displaying extra information.
Copy 
1
2
3
4
5
6

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

HTML output

Copy 
1
2
3
4
5
6

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

Copy 
1

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

See code examples

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 {
    boolean isVirtualReplica,
    boolean isRelevantSorted,
    boolean canRefine,
    function refine,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

Render options

Parameter Description
isVirtualReplica
type: boolean

Indicates whether the index is a virtual replica.
Copy 
1
2
3
4
5
6
7
8

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
type: boolean

Indicates whether the search result is relevantly sorted out.
Copy 
1
2
3
4
5
6
7
8

const renderRelevantSort = (renderOptions, isFirstRender) => {
  const { isRelevantSorted } = renderOptions;

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

  container.innerHTML = 'Showing ' +
    (isRelevantSorted ? 'relevant results.' : 'all results.');
};
canRefine
type: boolean
Required

Indicates if search state can be refined.
Copy 
1
2
3
4
5
6
7
8

const renderRelevantSort = (renderOptions, isFirstRender) => {
  const { canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector('#relevant-sort').innerHTML = '';
    return;
  }
};
refine
type: function

Sets relevancyStrictness.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

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
type: object

All original widget options forwarded to the render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const renderRelevantSort = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = '...';
};

// ...

search.addWidgets([
  customRelevantSort({
    container: document.querySelector('#relevant-sort'),
  })
]);

Create and instantiate the custom widget

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customRelevantSort = connectRelevantSort(
  renderRelevantSort
);

search.addWidgets([
  customRelevantSort({
    container: string|HTMLElement
    // Optional parameters
    templates: object
    cssClasses: object
  })
]);

Full example

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// 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'),
  })
]);
Did you find this page helpful?
InstantSearch.js v4