API Reference / InstantSearch.js / infiniteHits

infiniteHits

Signature 
instantsearch.widgets.infiniteHits({
  container: string|HTMLElement,
  // Optional parameters
  escapeHTML: boolean,
  showPrevious: boolean,
  templates: object,
  cssClasses: object,
  transformItems: function,
  cache: object,
});
See code examples
See live example

About this widget

The infiniteHits widget is used to display a list of results with a “Show more” button.

To configure the number of hits to show, use the hitsPerPage widget or the configure widget.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11

instantsearch.widgets.infiniteHits({
  container: '#infinite-hits',
  templates: {
    item: `
      <h2>
        {{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}
      </h2>
      <p>{{ description }}</p>
    `,
  },
});

Options

container
type: string|HTMLElement
Required

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

instantsearch.widgets.infiniteHits({
  container: '#infinite-hits',
});
escapeHTML
type: boolean
default: true
Optional

Escapes HTML entities from hits string values.
Copy 
1
2
3
4

instantsearch.widgets.infiniteHits({
  // ...
  escapeHTML: false,
});
showPrevious
type: boolean
default: false
Optional

Enable the button to load previous results.

The button is only displayed if the routing option is enabled in instantsearch and if the user is not on the first page. It’s possible to override this behavior by using connectors.
Copy 
1
2
3
4

instantsearch.widgets.infiniteHits({
  // ...
  showPrevious: true,
});
templates
type: object
Optional

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

instantsearch.widgets.infiniteHits({
  // ...
  templates: {
    // ...
  },
});
cssClasses
type: object
default: {}
Optional

The CSS classes to override.

  • root: the root element of the widget.
  • emptyRoot: the root container without results.
  • list: the list of results.
  • item: the list item.
  • loadPrevious: the “Show previous” button.
  • loadMore: the “Show more” button.
  • disabledLoadPrevious: the disabled “Show previous” button.
  • disabledLoadMore: the disabled “Show more” button.
Copy 
1
2
3
4
5
6
7
8
9
10

instantsearch.widgets.infiniteHits({
  // ...
  cssClasses: {
    root: 'MyCustomInfiniteHits',
    list: [
      'MyCustomInfiniteHits',
      'MyCustomInfiniteHits--subclass',
    ],
  },
});
transformItems
type: function
default: items => items
Optional

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

If you’re transforming an attribute using the highlight widget, you need to transform item._highlightResult[attribute].value.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

instantsearch.widgets.infiniteHits({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      name: item.name.toUpperCase(),
    }));
  },
});

/* or, combined with results */
instantsearch.widgets.infiniteHits({
  // ...
  transformItems(items, { results }) {
    return items.map((item, index) => ({
      ...item,
      position: { index, page: results.page },
    }));
  },
});
cache
type: object
default: in-memory cache object
Optional

The widget internally caches all loaded hits. By default, it uses its own internal in-memory cache implementation. We provide another implementation which uses sessionStorage, which is more persistent and lets you restore the scroll position when you leave and come back to the search page.

You can also provide your own implementation by providing a cache object with read and write methods.
Copy 
1
2
3
4
5
6
7

const sessionStorageCache =
  instantsearch.createInfiniteHitsSessionStorageCache();

instantsearch.widgets.infiniteHits({
  // ...
  cache: sessionStorageCache
});

Templates

empty
type: string|function
Optional

The template to use when there are no results. It exposes the results object.
Copy 
1
2
3
4
5
6

instantsearch.widgets.infiniteHits({
  // ...
  templates: {
    empty: 'No results for <q>{{ query }}</q>',
  },
});
item
type: string|function
Optional

The template to use for each result. This template receives an object containing a single record. The record has a new property __hitIndex for the relative position of the record in the list of displayed hits. You can leverage the highlighting feature of Algolia through the highlight function, directly from the template.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12

instantsearch.widgets.infiniteHits({
  // ...
  templates: {
    item: `
      <h2>
        {{ __hitIndex }}:
        {{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}
      </h2>
      <p>{{ description }}</p>
    `,
  },
});
showPreviousText
type: string|function
default: Show previous results
Optional

The template to use for the “Show previous” label.
Copy 
1
2
3
4
5
6

instantsearch.widgets.infiniteHits({
  // ...
  templates: {
    showPreviousText: 'Show previous',
  },
});
showMoreText
type: string|function
default: Show more results
Optional

The template to use for the “Show more” label.
Copy 
1
2
3
4
5
6

instantsearch.widgets.infiniteHits({
  // ...
  templates: {
    showMoreText: 'Show more',
  },
});

HTML output

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<div class="ais-InfiniteHits">
  <button class="ais-InfiniteHits-loadPrevious">
    Show previous
  </button>
  <ol class="ais-InfiniteHits-list">
    <li class="ais-InfiniteHits-item">
      ...
    </li>
    <li class="ais-InfiniteHits-item">
      ...
    </li>
    <li class="ais-InfiniteHits-item">
      ...
    </li>
  </ol>
  <button class="ais-InfiniteHits-loadMore">
    Show more
  </button>
</div>

Customize the UI with connectInfiniteHits

If you want to create your own UI of the infiniteHits widget, you can use connectors.

It’s a 3-step process:

// 1. Create a render function
const renderInfiniteHits = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customInfiniteHits = instantsearch.connectors.connectInfiniteHits(
  renderInfiniteHits
);

// 3. Instantiate
search.addWidgets([
  customInfiniteHits({
    // 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 renderInfiniteHits = (renderOptions, isFirstRender) => {
  const {
    object[] hits,
    object[] currentPageHits,
    object results,
    function sendEvent,
    boolean isFirstPage,
    boolean isLastPage,
    function showPrevious,
    function showMore,
    object widgetParams,
  } = renderOptions;

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

  // Render the widget
}

Rendering options

hits
type: object[]

The matched hits from the Algolia API. This returns the combined hits for all the pages that have been requested so far. You can leverage the highlighting feature of Algolia through the highlight function, directly from the connector’s render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { hits } = renderOptions;

  document.querySelector('#infinite-hits').innerHTML = `
    <ul>
      ${hits
        .map(
          item =>
            `<li>
              ${instantsearch.highlight({ attribute: 'name', hit: item })}
            </li>`
        )
        .join('')}
    </ul>
  `;
};
currentPageHits
type: object[]

The matched hits from the Algolia API for the current page. Unlike the hits parameter, this only returns the hits for the currently requested page. This can be useful if you want to handle how the new page of hits is going to be added to the list of search results. You can leverage the highlighting feature of Algolia through the highlight function, directly from the connector’s render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { currentPageHits } = renderOptions;
  const container = document.querySelector('#infinite-hits');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    container.appendChild(ul);

    return;
  }

  container.querySelector('ul').insertAdjacentHTML('beforeend', currentPageHits
    .map(
      hit =>
        `<li>
          ${instantsearch.highlight({ attribute: 'name', hit: item })}
        </li>`
    )
    .join(''));
};
results
type: object

The complete response from the Algolia API. It contains the hits but also metadata about the page, number of hits, etc. We recommend using hits rather than this option. You can also take a look at the stats widget if you want to build a widget that displays metadata about the search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { results } = renderOptions;

  if (isFirstRender) {
    return;
  }

  document.querySelector('#infinite-hits').innerHTML = `
    <ul>
      ${results.hits.map(item => `<li>${item.name}</li>`).join('')}
    </ul>
  `;
};
sendEvent
type: (eventType, hit, eventName) => void

The function to send click or conversion events. The view event is automatically sent when this connector renders hits. You can learn more about the insights middleware.

  • eventType: 'click' | 'conversion'
  • hit: Hit | Hit[]
  • eventName: string
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// For example,
sendEvent('click', hit, 'Product Added');
// or
sendEvent('conversion', hit, 'Order Completed');

/*
  A payload like the following will be sent to the `insights` middleware.
  {
    eventType: 'click',
    insightsMethod: 'clickedObjectIDsAfterSearch',
    payload: {
      eventName: 'Product Added',
      index: '<index-name>',
      objectIDs: ['<object-id>'],
      positions: [<position>],
      queryID: '<query-id>',
    },
    widgetType: 'ais.infiniteHits',
  }
*/
isFirstPage
type: boolean

Indicates whether the first page of hits has been reached.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12

const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { hits, isFirstPage } = renderOptions;

  document.querySelector('#infinite-hits').innerHTML = `
    <button ${isFirstPage ? 'disabled' : ''}>
      Static "Show previous" button
    </button>
    <ul>
      ${hits.map(item => `<li>${item.name}</li>`).join('')}
    </ul>
  `;
};
isLastPage
type: boolean

Indicates whether the last page of hits has been reached.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12

const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { hits, isLastPage } = renderOptions;

  document.querySelector('#infinite-hits').innerHTML = `
    <ul>
      ${hits.map(item => `<li>${item.name}</li>`).join('')}
    </ul>
    <button ${isLastPage ? 'disabled' : ''}>
      Static "Show more" button
    </button>
  `;
};
showPrevious
type: function

Loads the previous page of hits.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { hits, showPrevious } = renderOptions;
  const container = document.querySelector('#infinite-hits');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const button = document.createElement('button');
    button.textContent = 'Show previous';

    button.addEventListener('click', () => {
      showPrevious();
    });

    container.appendChild(button);
    container.appendChild(ul);

    return;
  }

  container.querySelector('ul').innerHTML = `
    ${hits.map(item => `<li>${item.name}</li>`).join('')}
  `;
};
showMore
type: function

Loads the next page of hits.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { hits, showMore } = renderOptions;
  const container = document.querySelector('#infinite-hits');

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const button = document.createElement('button');
    button.textContent = 'Show more';

    button.addEventListener('click', () => {
      showMore();
    });

    container.appendChild(ul);
    container.appendChild(button);

    return;
  }

  container.querySelector('ul').innerHTML = `
    ${hits.map(item => `<li>${item.name}</li>`).join('')}
  `;
};
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 renderInfiniteHits = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

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

// ...

search.addWidgets([
  customInfiniteHits({
    container: document.querySelector('#infinite-hits'),
  })
]);

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 customInfiniteHits = instantsearch.connectors.connectInfiniteHits(
  renderInfiniteHits
);

search.addWidgets([
  customInfiniteHits({
    // Optional parameters
    escapeHTML: boolean,
    showPrevious: boolean,
    transformItems: function,
  })
]);

Instance options

escapeHTML
type: boolean
default: true
Optional

Escapes HTML entities from hits string values.
Copy 
1
2
3

customInfiniteHits({
  escapeHTML: false,
});
showPrevious
type: boolean
default: false
Optional

Enable the button to load previous results.
Copy 
1
2
3

customInfiniteHits({
  showPrevious: true,
});
transformItems
type: function
default: items => items
Optional

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

If you’re transforming an attribute using the highlight widget, you need to transform item._highlightResult[attribute].value.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

customInfiniteHits({
  transformItems(items) {
    return items.map(item => ({
      ...item,
      name: item.name.toUpperCase(),
    }));
  },
});

/* or, combined with results */
customInfiniteHits({
  transformItems(items, { results }) {
    return items.map((item, index) => ({
      ...item,
      position: { index, page: results.page },
    }));
  },
});

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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

// Create the render function
const renderInfiniteHits = (renderOptions, isFirstRender) => {
  const {
    hits,
    widgetParams,
    showPrevious,
    isFirstPage,
    showMore,
    isLastPage,
  } = renderOptions;

  if (isFirstRender) {
    const ul = document.createElement('ul');
    const previousButton = document.createElement('button');
    previousButton.className = 'previous-button';
    previousButton.textContent = 'Show previous';

    previousButton.addEventListener('click', () => {
      showPrevious();
    });

    const nextButton = document.createElement('button');
    nextButton.className = 'next-button';
    nextButton.textContent = 'Show more';

    nextButton.addEventListener('click', () => {
      showMore();
    });

    widgetParams.container.appendChild(previousButton);
    widgetParams.container.appendChild(ul);
    widgetParams.container.appendChild(nextButton);

    return;
  }

  widgetParams.container.querySelector('.previous-button').disabled = isFirstPage;
  widgetParams.container.querySelector('.next-button').disabled = isLastPage;

  widgetParams.container.querySelector('ul').innerHTML = `
    ${hits
      .map(
        item =>
          `<li>
            ${instantsearch.highlight({ attribute: 'name', hit: item })}
          </li>`
      )
      .join('')}
  `;
};

// Create the custom widget
const customInfiniteHits = instantsearch.connectors.connectInfiniteHits(
  renderInfiniteHits
);

// Instantiate the custom widget
search.addWidgets([
  customInfiniteHits({
    container: document.querySelector('#infinite-hits'),
    showPrevious: true,
  })
]);

Sending Click and Conversion events

Please refer to the guide on Sending Insight Events to learn about sending events from any InstantSearch widget.

Guides Send Events with InstantSearch.js
Did you find this page helpful?
InstantSearch.js v4