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() {
  var 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.

var 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
1a
1b
1c
1d

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen

Disable appending by not setting append, for loading JSON or adding your own append behavior like with Masonry or Isotope.
// 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-existant 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 responseType: 'document'.

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

This demo uses button to show that Infinite Scroll will not attempt to load page 5 and that the button will be hidden when there are no more pages to load.

1a
1b
1c
1d

End of content

No more pages to load

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 ) {
    var nextIndex = this.loadCount + 2;
    return 'news/blog-p' + nextIndex + '.html';
  }
}

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

checkLastPage: false
// disabled
1a
1b
1c
1d

End of content

No more pages to load

prefill

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

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

1a

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen

responseType

Sets the type of response returned by the page request. See MDN docs XMLHttpRequest.responseType.

// responseType: 'document'
// default, return next page's DOM

Set responseType: 'text' to return flat text for loading JSON.

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

$container.on( 'load.infiniteScroll', function( event, response ) {
  // parse JSON
  var data = JSON.parse( response );
  // do something with JSON...
});

See demos on CodePen:

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
var $grid = $('.grid').masonry({
  // Masonry options...
  itemSelector: '.grid__item', 
});

// get Masonry instance
var 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
var msnry = new Masonry( '.grid', {
  // Masonry options...
  itemSelector: '.grid__item', 
});

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

outlayer requires imagesLoaded. It already is included with infinite-scroll.pkgd.js, but not with Infinite Scroll when installed with a package manager like npm or Yarn. You need to install and require imagesloaded separately. See details in Extras.

With Isotope:

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

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

// init Infinite Scroll
$grid.infiniteScroll({
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: iso,
});
// with Isotope & vanilla JS
// init Isotope
var iso = new Isotope( '.grid', {
  // Isotope options...
  itemSelector: '.grid__item', 
});

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

With Packery:

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

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

// init Infinite Scroll
$grid.infiniteScroll({
  // Infinite Scroll options...
  append: '.grid__item',
  outlayer: pckry,
});
// with Packery & vanilla JS
// init Packery
var pckry = new Packery( '.grid', {
  // Packery options...
  itemSelector: '.grid__item', 
});

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

scrollThresold: 100
// trigger scrollThreshold event when viewport is <100px from bottom of scroll area
1a
1b
1c
1d

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen

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
});
1a
1b
1c
1d

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen

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
});
1a
1b
1c
1d

Edit this demo or vanilla JS demo on CodePen

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 the browser history and URL.

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: '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'
1a
1b
1c
1d

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen

button

Enables a button to load pages on click. The button will state will be hooked in to 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
1a
1b
1c
1d

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen

debug

Logs events and state changes to the console.

debug: true

View logs in your browser's Developer Console.

1a
1b
1c
1d

End of content

No more pages to load

Edit this demo or vanilla JS demo on CodePen