Filter an ampersand collection by limit and offset

Downloads in past


423.0.08 years ago9 years agoMinified + gzip package size for ampersand-paginated-subcollection in KB


Lead Maintainer: Michael Garvin


Paginated subset of a collection. Only emits reset events.
This allows you to have a paginated version of anything that acts like an ampersand-collection That you can quickly paginate through without affecting its parent.
Part of the Ampersand.js toolkit for building clientside applications.


npm install ampersand-paginated-subcollection


var WidgetCollection = require('./mycollection');
var PaginatedSubcollection = require('ampersand-paginated-subcollection');

var widgets = new WidgetCollection();


// This will create a collection-like object
// that will only include 10 widgets starting
// at offset 0
var widgetPage = new PaginatedSubcollection(widgets, {
    limit: 10

//Move to the next 10 widgets
widgetPage.configure({offset: 10});

API reference

new PaginatedSubcollection(collection, config);

  • collection {Collection} An instance of ampersand-collection or Backbone.Collection that contains our full set of models.
  • config {Object} optional The config object which can take the following options
* `limit` {Number} [optional] If specified will limit the number of models to this maximum number.
* `offset` {Number} Default: `0`. This is the index of the start of the current page of models to pull from `collection`

.configure(config, reset)

This is how you paginate post-init
  • config {Object} Same config object as what you pass to init.
  • reset {Boolean} Default: false. If true, a reset event will be emitted regardless of whether or not the limit or offset were changed.


  • index {Number} returns model as specified index in the paginated collection.


The paginated collection maintains a read-only length property that simply proxies to the array length of the models it contains.


The array of filtered models with offset and/or limit applied (if set).


This property is present and set to true. see ampersand-collection for more info


PaginatedSubcollection attaches extend to the constructor so if you want to add custom methods to your PaginatedSubcollection constructor, it's easy:
var PaginatedSubcollection = require('ampersand-paginated-subcollection');

// this exports a new constructor that includes
// the methods you passed on the prototype while
// maintaining the inheritance chain for instanceof
// checks.
module.exports = PaginatedSubcollection.extend({
    myMethod: function () { ... },
    myOtherMethod: function () { ... }

This is done by using: ampersand-class-extend

A note about events

Because ampersand-view and its ilk cache views, it is really inexpensive to simply emit a reset whenever we want to change the pagination. This prevents us from having to do internal indexOf tests (which are very slow) in order to determine when to bubble up individual events. This means that reset is the only event that this module will emit, whenever something in the parent collection warrants this happening.

REST pagination

This module does not do REST pagination with the server, that is something that is done via ampersand-rest-collection.


If you like this follow @HenrikJoreteg on twitter.