Infinite Scroll with InstantSearch.js

The infinite list is a very common pattern to display a list of results. This pattern has two variants:

• With a button to click on at the end of the list of results
• With a listener on the scroll event that is called when the list of results reaches the end

You can cover those two different implementations with InstantSearch.js. The former is covered by the built-in infiniteHits widget and the latter is covered by the connectInfiniteHits connector. This guide focuses on the second implementation using the Intersection Observer API. A browser API is used in the example but the concepts can be applied to any kind of infinite scroll library. You can find the complete example on GitHub.

The Intersection Observer API isn’t yet widely supported. You may want to consider using a polyfill.

Display a list of hits

The first step to creating an infinite scroll widget is to render the results with the infiniteHits connector. You can find more information about the connectors in the dedicated guide.

All examples in this guide assume you’re including InstantSearch.js in your web page via a CDN. If you’re using it with a package manager, you should adjust the way you import InstantSearch.js and its widgets. Read How to install InstantSearch.js for more information.

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
const infiniteHits = instantsearch.connectors.connectInfiniteHits(
  (renderArgs, isFirstRender) => {
    const { hits, showMore, widgetParams } = renderArgs;
    const { container } = widgetParams;

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

      return;
    }

    container.querySelector('ul').innerHTML = hits
      .map(
        hit =>
          `<li>
            <div class="ais-Hits-item">
              <header class="hit-name">
                ${instantsearch.highlight({ attribute: 'name', hit })}
              </header>
              <img src="${hit.image}" align="left" />
              <p class="hit-description">
                ${instantsearch.highlight({ attribute: 'description', hit })}
              </p>
              <p class="hit-price">$${hit.price}</p>
            </div>
          </li>`
      )
      .join('');
  }
);

Track the scroll position

Now you have your list of results, the next step is to track the scroll position to determine when the rest of the content needs to be loaded. For this purpose, the Intersection Observer API is used. To track when the bottom of the list enters the viewport, you observe a “sentinel” element. This trick is used to avoid observing all the items of the results. You can reuse the same element across different renders. You can find more information about this pattern on the Web Fundamentals website.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const infiniteHits = instantsearch.connectors.connectInfiniteHits(
  (renderArgs, isFirstRender) => {
    const { hits, showMore, widgetParams } = renderArgs;
    const { container } = widgetParams;

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

      return;
    }

    // ...
  }
);

Once you have the reference to the “sentinel” element, you can create the Intersection Observer instance to observe when this element enters the page. You can provide options to the Intersection Observer API to adjust to your needs.

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
const infiniteHits = instantsearch.connectors.connectInfiniteHits(
  (renderArgs, isFirstRender) => {
    const { hits, showMore, widgetParams } = renderArgs;
    const { container } = widgetParams;

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

      const observer = new IntersectionObserver(entries => {
        entries.forEach(entry => {
          if (entry.isIntersecting) {
            // In that case we can refine
          }
        });
      });

      observer.observe(sentinel);

      return;
    }

    // ...
  }
);

Retrieve more results

Now that you can track when you reach the end of the results, you can use the showMore function inside the callback function of the observer. But you should only trigger the function when you still have results to retrieve. For this use case, the connector provides a parameter isLastPage that indicates if you still have results or not.

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
let lastRenderArgs;

const infiniteHits = instantsearch.connectors.connectInfiniteHits(
  (renderArgs, isFirstRender) => {
    const { hits, showMore, widgetParams } = renderArgs;
    const { container } = widgetParams;

    lastRenderArgs = renderArgs;

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

      const observer = new IntersectionObserver(entries => {
        entries.forEach(entry => {
          if (entry.isIntersecting && !lastRenderArgs.isLastPage) {
            showMore();
          }
        });
      });

      observer.observe(sentinel);

      return;
    }

    // ...
  }
);

Go further than 1000 hits

By default Algolia limits the number of hits you can retrieve for a query to 1000; when doing an infinite scroll, you usually don’t want to go over this limit.

1
2
3
$index->setSettings([
  'paginationLimitedTo' => 1000
]);

1
2
3
index.set_settings({
  paginationLimitedTo: 1000
})

1
2
3
4
5
index.setSettings({
  paginationLimitedTo: 1000
}).then(() => {
  // done
});

1
2
3
index.set_settings({
    'paginationLimitedTo': 1000
})

1
2
3
4
5
6
7
8
let settings = Settings()
  .set(\.paginationLimitedTo, to: 1000)

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
val settings = settings {
    paginationLimitedTo = 1000
}

index.setSettings(settings)

1
2
3
4
IndexSettings settings = new IndexSettings();
settings.PaginationLimitedTo = 1000;

index.SetSettings(settings);

1
2
3
index.setSettings(
  new IndexSettings().setPaginationLimitedTo(1000)
);

1
2
3
res, err := index.SetSettings(search.Settings{
  opt.PaginationLimitedTo(1000),
})

1
2
3
4
5
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    paginationLimitedTo = Some(1000)
  )
}

Disabling the limit doesn’t mean that you can go until the end of the hits, but just that Algolia will go as far as possible in the index to retrieve results in a reasonable time.

Now you should have a complete infinite scroll experience.

The complete source code of the example is on GitHub.