Need help with ember-impagination?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

122 Stars 12 Forks MIT License 353 Commits 31 Opened issues


An Ember Addon that puts the fun back in asynchronous, paginated datasets

Services available


Need anything else?

Contributors list


npm version Ember Observer Score Build Status Netlify Status

Ember-Impagination is an Ember binding for Impagination, a front-end data-layer for the paginated API on your server. Ember-Impagination leverages the power of Glimmer and provides your component the data it needs to render quickly each and every time.

Impagination README: Whatever your use-case: infinite scrolling lists, a carousel browser, or even a classic page-by-page result list, Impagination frees you to focus on what you want to do with your data, not the micro-logistics of when to fetch it. All you provide Impagination is the logic to fetch a single page, plus how many pages you want it to pre-fetch ahead of you, and it will figure out the rest. Impagination is built using an event-driven immutable style, so it is ideal for use with UI frameworks like Ember . . .

Hence, we present Ember-Impagination.

Ember-Impagination provides you with a component,

{{impagination-dataset as |data|}}
, you can use to feed data into your templates while having that data look exactly like an

Note: Ember-Impagination does not provide any of the visual elements in a system like infinite scroll. You'll still need to use a special component like

. Instead, Ember-Impagination simplifies feeding your components fetched data.


  • ember install ember-impagination


Ember-Impagination Demo

The demo presents a finite scroll implementation of Ember-Impagination. It scrolls through the ROYGBIV color spectrum by loading and unloading pages of records, where each record is a unique color-hue. At the top of the demo, you will find a visualization for pages. Resolved (Loaded) Pages are green, Pending (Loading) pages are white, and Unrequested (Unloaded) pages are black. The white-bar represents the top-most index of the scroll view.


The demo is implemented using virtual-each due to the simplicity of the component. However, Ember-Impagination can also be utilized with other components like ember-collection, or even a simple

. By design, Ember-Impagination leverages Glimmer and yields paginated data from your server's API to components which expect an array.


Impagination-Dataset Component

To create an

there are two required parameters,
. Optional parameters include
. See Impagination for detailed attribute descriptions.
{{!-- app/templates/index.hbs --}}
  as |records|}}
Total Records: {{records.length}}
{{#each records as |record|}}
Record {{}}
{{/each}} {{/impagination-dataset}}

Now, in your route, you can define the actual

functions that tell
how it should request each individual page, and the
which specify how many pages to request ahead/behind.
// app/route/record.js
export default Ember.Route.extend({
  pageSize: 5, // fetch records in pages of 5 (*required*)
  loadHorizon: 10, // fetch  records "inclusive" (+/- loadHorizon)   of the current readOffset (default: pageSize)
  //unloadHorizon: Infinity, // unload records "exclusive" (+/- unloadHorizon) of the current readOffset (default: Infinity)
  //readOffset: 0,           // the initial readOffset of the dataset (default: 0)

// fetch() function is invoked whenever a page is requested within the loadHorizon fetch: function(pageOffset, pageSize, stats) { // function which returns a "thenable" (required) let params = { page: pageOffset }; // fetch a page of records at the pageOffset return"record", params).then(data => { let meta = data.get("meta"); stats.totalPages = meta.totalPages; return data.toArray(); }); }, // unfetch() function is invoked whenever a page is unloaded unfetch: function(records, pageOffset) { "record", records .map(r => .then(function(records) { records.forEach(record => record.deleteRecord()); }) ); } });

This setup will immediatly call fetch twice (for records 0-4 [page 0] and records 5-9 [page 1])

Total Records: 10
Record 0
Record 1
Record 2
Record 9

Passing the Fetch Function

In Ember 1.13 and above, we can use closure-actions to pass the fetch function into

{{#impagination-dataset fetch=(action "fetch")}}
// app/route/record.js
export default Ember.Route.extend({
  // fetch() function is invoked whenever a page is requested within the loadHorizon
  actions: {
    fetch(pageOffset, pageSize, stats) {
      // function which returns a "thenable" (*required*)
      let params = {
        query: query
      // fetch a page of records at the pageOffset
      return"record", params).then(data => {
        let meta = data.get("meta");
        stats.totalPages = meta.totalPages;
        return data.toArray();

We do not recommend defining

inside your controller because it requires injecting the store into the controller

In Ember 1.12 and below we cannot define

in our actions hash. We must instead bind it to our controller.
{{#impagination-dataset fetch=fetch)}}
// app/route/record.js
export default Ember.Route.extend({
    fetch: function(pageOffset, pageSize, stats) {
    setupController: function(controller, model){
      this._super.apply(this, arguments);
      controller.set('fetch', this.fetch.bind(this));

Filtering Records

We fetch records using an immutable style, but we often require filtering by mutable records in our dataset. To enable filtering, pass a filter

as you would to
. The filters are applied as soon as a page is resolved. To filter a page at other times in your application see
{{#impagination-dataset fetch=(action "fetch") filter=filterCallback}}
// app/route/record.js
export default Ember.Route.extend({
  // filter() function is invoked whenever a page is resolved or refiltered
  filterCallback(record /*, index, records*/) {
    // function which rejects deleted records
    return !record.get("isDeleted");

Dataset API

There are a number actions to update the dataset.

Updating the Dataset

| Actions | Parameters | Description | | ------------- | :--------------: | :------------------------------------------------------------------------------------------------------------- | | refilter | [filterCallback] | Reapplies the filter for all resolved pages. If

is provided, applies and sets the new filter. | | reset | [offset] | Unfetches all pages and clears the
. If
is provided, fetches records starting at
. | | setReadOffset | [offset] | Sets the
and fetches records resuming at
| | ~~reload~~ | ~~[index]~~ | Removed in
release. Please use

Updating the State

| Actions | Parameters | Defaults | Description | | ------- | :---------: | :----------------------- | :------------------------------------- | | post | data, index | index = 0 | Creates record with

. | | put | data, index | index = state.readOffset | Merges
into record at
. | | delete | index | index= state.readOffset | Deletes record at
. |

These functions can be called from the route/controller or from child components in the handlebars templates. In the examples below, we

the dataset upon search queries through the {{search-pane}} component using both options.

resetting from the parent route

In order to call dataset actions from the route, we will have to observe the latest dataset and dataset-actions with the

{{#search-pane search=(action "search")}}
  {{#impagination-dataset on-observe=(action "observeDataset") fetch=(action "fetch") as |dataset|}}
    {{#ember-collection items=dataset as |record|}}
      {{chat-search-result result=record}}
_resetDataset() {

actions: { observeDataset: function(dataset) { this.set('dataset', dataset); }, search(query) { this.set('searchParams', query); this._resetDataset(); }, fetch(pageOffset, pageSize, stats) { params = this.get('params'); return'records', params); } }

resetting from child components

Here we do not need to utilize

parameter. The
action is simply called by a child component.
{{#impagination-dataset fetch=(action "fetch") as |dataset|}}
  {{!-- reset dataset and start fetching at record index 0 --}}
  {{#search-pane search=(action "search") on-search-results=(action dataset.reset 0)}}
      {{#ember-collection items=dataset as |record|}}
        {{chat-search-result result=record}}

Create your own Dataset


is not an ideal component for your unique
needs, you can get into the nitty gritty, and use
directly. If you find yourself creating your own
, let us know how you are using
. It may be a reason for improvements or another ember addon.
import Dataset from 'impagination/dataset';

let dataset = new Dataset({ pageSize: 5, fetch: function(pageOffset, pageSize, stats) { return new Ember.RSVP.Promise((resolve)=> { let data = // Array resolve(data); },

return'record', params).then((data) => {
  let meta = result.get('meta');
  stats.totalPages = meta.totalPages;
  return result.toArray();

}, observe: (state) => {} });

Running tests

  • ember test
    – Runs the test suite on the current Ember version
  • ember test --server
    – Runs the test suite in "watch mode"
  • ember try:each
    – Runs the test suite against multiple Ember versions

Running the dummy application

For more information on using ember-cli, visit

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms, which can be found in the
file in this repository.


This project is licensed under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.