Options

Loading

path

Determines the URL for the next page. Required.

Set to a selector string of a link to the next page to use its href value for incremental page numbers (2, 3, 4...).

<a class="pagination__next" href="/page/2">Next</a>

path: '.pagination__next'
// parse href of element
// => /page/2, /page/3, page/4 ...

View full page demo with path selector string.

Set to a string with {{#}} for the incremental page number.

path: 'news/blog-p{{#}}.html'
// replace {{#}} with page number
// => news/blog-p2.html, news/blog-p3.html, news/blog-p4.html...

Set to a function that returns the URL for page URLs that do not use incremental numbers. For example, A List Apart articles increment by 10. Use pageIndex and loadCount properties to calculate the URL.

path: function() {
  let pageNumber = ( this.loadCount + 1 ) * 10;
  return `/articles/P${pageNumber}`;
}
// => /articles/P10, /articles/P20, /articles/P30 ...

For another example, this documentation site uses a function to get the next URL from an array.

let nextPages = [
  'index',
  'options',
  'api',
  'events',
  'extras',
  'license',
];

$('.container').infiniteScroll({
  path: function() {
    return nextPages[ this.loadCount ] + '.html';
  },
  // options...
});

This technique is used in all the CodePen demos.

append

Appends selected elements from loaded page to the container. Disabled by default append: false

append: '.post'
// append .post elements from next page to container

// disabled by default
// append: false
// do not append any content on page load

checkLastPage

Checks if Infinite Scroll has reached the last page. This prevents Infinite Scroll from requesting a non-existent page. last event will be triggered when last page is reached. Enabled by default checkLastPage: true.

When set to checkLastPage: true and path set to a selector string, Infinite Scroll will check if the loaded page has the path selector. Requires responseBody: 'text' and domParseResponse: true.

// checkLastPage: true,
// checkLastPage enabled by default
path: '.pagination__next',
// check last page for .pagination__next

If path is set to a string with {{#}} or a function, set checkLastPage to a selector string to check for that selector.

path: 'news/blog-p{{#}}.html',
// path set to string with {{#}}
checkLastPage: '.pagination__next',
// check page for .pagination__next

If path is set a function, Infinite Scroll will check if that function returns a value.

path: function() {
  // no value returned after 4th loaded page
  if ( this.loadCount < 4 ) {
    let nextIndex = this.loadCount + 2;
    return `news/blog-p${nextIndex}.html`;
  }
}

When disabled, Infinite Scroll will attempt to load the next page.

checkLastPage: false
// disabled

prefill

Loads and appends pages on intialization until scroll requirement is met.

prefill: true
// load pages on init until user can scroll

responseBody

Sets the Response body interface method, on the response returned from fetch request. Default responseBody: 'text'

Set responseBody: 'json' to return JSON.

$container.infiniteScroll({
  path: '/api/page{{#}}.json',
  append: false,
  responseBody: 'json',
});

$container.on( 'load.infiniteScroll', function( event, data ) {
  // data is JSON
});

See demos on CodePen:

• Loading JSON
• Loading JSON, vanilla JS
• Loading JSON with Masonry
• Loading JSON with Masonry, vanilla JS

domParseResponse

When enabled parses the response body into a DOM. Enabled by default domParseResponse: true

Disable to load flat text.

$container.infiniteScroll({
  path: '/api/page{{#}}.yml',
  append: false,
  domParseResponse: false,
});

$container.on( 'load.infiniteScroll', function( event, body ) {
  // body is text
});

fetchOptions

Sets method, headers, CORS mode, and other options for the fetch request. See Supplying request options on MDN for more details.

fetchOptions: {
  mode: 'cors',
  cache: 'no-cache',
  credentials: 'same-origin',
  headers: {
    'X-Session-Id': '33vscths658h7996d324rqft1s',
  },
},

Set fetchOptions to a function that returns an object to dynamically set fetch request options for each request.

fetchOptions: function() {
  return {
    mode: 'cors',
    cache: 'no-cache',
    credentials: 'same-origin',
    headers: {
      'X-Session-Id': getSessionId(),
    },
  };
},

outlayer

Integrates Masonry, Isotope or Packery. Infinite Scroll will add appended items to the layout.

outlayer: instance

instance Masonry, Isotope, or Packery The layout class instance

// with Masonry & jQuery
// init Masonry
let $grid = $('.grid').masonry({
  // Masonry options...
  itemSelector: '.grid__item',
});

// get Masonry instance
let msnry = $grid.data('masonry');

// init Infinite Scroll
$grid.infiniteScroll({
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: msnry,
});

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen

// with Masonry & vanilla JS
// init Masonry
let msnry = new Masonry( '.grid', {
  // Masonry options...
  itemSelector: '.grid__item',
});

// init Infinite Scroll
let infScroll = new InfiniteScroll( '.grid', {
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: msnry,
});

With Isotope:

// with Isotope & jQuery
// init Isotope
let $grid = $('.grid').isotope({
  // Isotope options...
  itemSelector: '.grid__item',
});

// get Isotope instance
let iso = $grid.data('isotope');

// init Infinite Scroll
$grid.infiniteScroll({
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: iso,
});

// with Isotope & vanilla JS
// init Isotope
let iso = new Isotope( '.grid', {
  // Isotope options...
  itemSelector: '.grid__item',
});

let infScroll = new InfiniteScroll( '.grid', {
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: iso,
});

With Packery:

// with Packery & jQuery
// init Packery
let $grid = $('.grid').packery({
  // Packery options...
  itemSelector: '.grid__item',
});

// get Packery instance
let pckry = $grid.data('packery');

// init Infinite Scroll
$grid.infiniteScroll({
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: pckry,
});

// with Packery & vanilla JS
// init Packery
let pckry = new Packery( '.grid', {
  // Packery options...
  itemSelector: '.grid__item',
});

let infScroll = new InfiniteScroll( '.grid', {
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: pckry,
});

onInit

Called on initialization. Useful for initial binding events with vanilla JS.

onInit: function() {
  this.on( 'load', function() {
    console.log('Infinite Scroll load')
  });
}

Scrolling

scrollThreshold

Sets the distance between the viewport to scroll area for scrollThreshold event to be triggered. Default: scrollThreshold: 400.

scrollThreshold: 100
// trigger scrollThreshold event when viewport is <100px from bottom of scroll area

Disable loading on scroll and the scrollThreshold event with scrollThreshold: false. This is useful if loading with button.

scrollThreshold: false
// disable loading on scroll
// and scrollThreshold event from triggering

elementScroll

Sets scroller to an element for overflow element scrolling. Disabled by default, window is used to scroll.

We recommend disabling history with elementScroll.

Set elementScroll to a selector string or element to use a different parent element. This is useful if a status element or button is at the bottom of the scroll area.

<!-- .sidebar is scrollable -->
<div class="sidebar">
  <!-- .container has scroll content -->
  <div class="container">
    <article class="post">...</article>">...</div>
    <article class="post">...</article>">...</div>
    ...
  </div>
  <!-- status is at bottom of scroll -->
  <div class="page-load-status">
    <p class="infinite-scroll-request">Loading...</p>
    ...
  </div>
</div>

// content will be appended to .container
$('.container').infiniteScroll({
  // options...
  elementScroll: '.sidebar',
  // use .sidebar overflow element scrolling
});

Set elementScroll: true to use the container element.

<!-- .container is scrollable and has scroll content -->
<div class="container">
  <article class="post">...</article>">...</div>
  <article class="post">...</article>">...</div>
  ...
</div>

// content will be appended to .container
$('.container').infiniteScroll({
  // options...
  elementScroll: true,
  // use .container overflow element scrolling
});

loadOnScroll

Loads next page when scroll crosses over scrollThreshold. Enabled by default loadOnScroll: true.

Disable loadOnScroll if you do not want to load pages on scroll, but still want the scrollThreshold event triggered.

loadOnScroll: false
// disable loading pages on scroll
// scrollThreshold event still triggered

Otherwise, you can disable both loading on scroll and scrollThreshold event by disabling scrollThreshold.

scrollThreshold: false
// disable loading pages on scroll
// and scrollThreshold event

History options

history

Changes page URL and browser history.

Enabled by default history: 'replace' will use history.replaceState() to change the current history entry. Going back in the browser will return the user to previous site.

View full page demo with history: 'replace'.

Set history: false to disable.

history: false
// disable changing URL and browser history

Set history: 'push' to use history.pushState() to create new history entries for each page change. Going back in the browser will load the previous page.

history: 'push'
// create new history entry for each page

When enabled with append enabled, history will be changed when the appended page is scrolled into view. Users may scroll up and down, and history will reflect the URL of the content in the view.

When enabled with append disabled, history will be changed only when a page is loaded.

historyTitle

Updates the window title. Requires history enabled. Enabled by default historyTitle: true.

historyTitle: false
// do not change window title when history changes

UI

hideNav

Hides navigation element.

<!-- hide pagination with infinite scroll enabled -->
<div class="pagination">
  <span class="pagination__current">Page 1</span>
  <a class="pagination__next" href="/page/2">Next</a>
</div>

hideNav: '.pagination'

Edit this demo or vanilla JS demo on CodePen

status

Displays status elements indicating state of page loading. Within the selected element:

• .infinite-scroll-request element will be displayed on request
• .infinite-scroll-last element will be displayed on last
• .infinite-scroll-error element will be displayed on error

The selected status element will be hidden on append or load.

<div class="page-load-status">
  <p class="infinite-scroll-request">Loading...</p>
  <p class="infinite-scroll-last">End of content</p>
  <p class="infinite-scroll-error">No more pages to load</p>
</div>

status: '.page-load-status'

button

Enables a button to load pages on click. The button state is changed by Infinite Scroll events:

• Disabled while loading on request
• Re-enabled after page is loaded on load
• Hidden when no more pages to load on error and last

button: '.view-more-button',
// load pages on button click
scrollThreshold: false,
// disable loading on scroll

debug

Logs events and state changes to the console.

debug: true