New! Infinite Scroll v3 · Back & refresh button friendly

Extras

Extra examples

Module loaders

RequireJS

Isotope supports RequireJS.

You can require isotope.pkgd.js.

requirejs( [
  'path/to/isotope.pkgd.js',
], function( Isotope ) {
  var iso = new Isotope( '.grid', {...});
});

Any layout mode that’s not included, will need to be required separately

requirejs( [
  'path/to/isotope.pkgd.js',
  'path/to/masonry-horizontal.js'
], function( Isotope ) {
  var iso = new Isotope( '.grid', {
    layoutMode: 'masonryHorizontal'
  });
});

To use Isotope as a jQuery plugin with RequireJS and isotope.pkgd.js, you need to run jQuery bridget.

// require the require function
requirejs( [ 'require', 'jquery', 'path/to/isotope.pkgd.js' ],
  function( require, $, Isotope ) {
    // require jquery-bridget, it's included in isotope.pkgd.js
    require( [ 'jquery-bridget/jquery-bridget' ],
    function( jQueryBridget ) {
      // make Isotope a jQuery plugin
      jQueryBridget( 'isotope', Isotope, $ );
      // now you can use $().isotope()
      $('.grid').isotope({...});
    }
  );
});

Or, you can manage dependencies with Bower. Set baseUrl to bower_components and set a path config for all your application code.

requirejs.config({
  baseUrl: 'bower_components/',
  paths: {
    app: '../'
  }
});

requirejs( [
  'isotope/js/isotope',
  'app/my-component.js'
], function( Isotope, myComp ) {
  var iso = new Isotope( '.grid', {...});
});

You can require Bower dependencies and use Isotope as a jQuery plugin with jQuery Bridget.

requirejs.config({
  baseUrl: '../bower_components',
  paths: {
    jquery: 'jquery/jquery'
  }
});

requirejs( [
    'jquery',
    'isotope/js/isotope',
    'jquery-bridget/jquery-bridget'
  ],
  function( $, Isotope, jQueryBridget ) {
    // make Isotope a jQuery plugin
    jQueryBridget( 'isotope', Isotope, $ );
    // now you can use $().isotope()
    $('.grid').isotope({...});
});

Browserify

Isotope works with Browserify. Install Isotope with npm.

npm install isotope-layout
var Isotope = require('isotope-layout');

var iso = new Isotope( '.grid', {
  // options...
});

Install and require layout modes that are not included.

npm install isotope-cells-by-row
var Isotope = require('isotope-layout');
// add cellsByRow layout mode
require('isotope-cells-by-row')

var iso = new Isotope( '.grid', {
  layoutMode: 'cellsByRow'
});

To use Isotope as a jQuery plugin with Browserify, you need to use jQuery Bridget

npm install jquery
npm install jquery-bridget
var $ = require('jquery');
var jQueryBridget = require('jquery-bridget');
var Isotope = require('isotope-layout');
// make Isotope a jQuery plugin
jQueryBridget( 'isotope', Isotope, $ );
// now you can use $().isotope()
$('.grid').isotope({
  // options...
});

Webpack

Install Isotope with npm.

npm install isotope-layout

In your config file, webpack.config.js, add these resolve aliases.

module.exports = {
  resolve: {
    alias: {
      'masonry': 'masonry-layout',
      'isotope': 'isotope-layout'
    }
  }
};

(This hack is required because of an issue with how Webpack loads dependencies. +1 this issue on GitHub to help get this issue addressed.)

You can then require('isotope-layout').

// main.js
var Isotope = require('isotope-layout');

var iso = new Isotope( '.grid', {
  // options...
});

Run webpack.

webpack main.js bundle.js

Layout modes and jQuery plugin functionality need to be installed separately, similar to using Browserify.

Bootstrap

You can use Isotope layouts with Bootstrap grid system. This example will display a fluid grid of 3 columns, using col-xs-4 as columnWidth.

<div class="container-fluid">
  <!-- add extra container element for Masonry -->
  <div class="grid">
    <!-- add sizing element for columnWidth -->
    <div class="grid-sizer col-xs-4"></div>
    <!-- items use Bootstrap .col- classes -->
    <div class="grid-item col-xs-8">
      <!-- wrap item content in its own element -->
      <div class="grid-item-content">...</div>
    </div>
    <div class="grid-item col-xs-4">
      <div class="grid-item-content">...</div>
    </div>
    ...
  </div>
</div>
$('.grid').isotope({
  itemSelector: '.grid-item', // use a separate class for itemSelector, other than .col-
  percentPosition: true,
  masonry: {
    columnWidth: '.grid-sizer'
  }
});

Use multiple .col- classes on item elements to use Bootstrap’s grid media queries to responsively change column sizes. This example will use 2, then 3, then 4 columns at different screen sizes.

<div class="container-fluid">
  <div class="grid">
    <!-- 2 col grid @ xs, 3 col grid @ sm, 4 col grid @ md -->
    <div class="grid-sizer col-xs-6 col-sm-4 col-md-3"></div>
    <!-- 1 col @ xs, 2 col @ sm, 2 col @ md -->
    <div class="grid-item col-xs-6 col-sm-8 col-md-6">
      <div class="grid-item-content">...</div>
    </div>
    <!-- 1 col @ xs, 1 col @ sm, 1 col @ md -->
    <div class="grid-item col-xs-6 col-sm-4 col-md-3">
      <div class="grid-item-content">...</div>
    </div>
    ...
  </div>
</div>

Animating item size

You cannot transition or animate the size of an item element and properly lay out. But there is a trick — you can animate a child element of the item element.

<div class="grid">
  <!-- items have grid-item-content child elements -->
  <div class="grid-item">
    <div class="grid-item-content"></div>
  </div>
  ...
/* item is invisible, but used for layout
item-content is visible, and transitions size */
.grid-item,
.grid-item-content {
  width: 60px;
  height: 60px;
}
.grid-item-content {
  background: #09D;
  transition: width 0.4s, height 0.4s;
}

/* both item and item content change size */
.grid-item.is-expanded,
.grid-item.is-expanded .grid-item-content {
  width: 180px;
  height: 120px;
}

Click to item to toggle size

Edit this demo or vanilla JS demo on CodePen

This technique works on items with responsive, percentage widths. Although, it does require a bit more JS. Check out the example on CodePen to see how it’s done.

.grid-item {
  width: 20%;
  height: 60px;
}

.grid-item-content {
  width:  100%;
  height: 100%;
  background: #09D;
  transition: width 0.4s, height 0.4s;
}
/* item has expanded size */
.grid-item.is-expanded {
  width: 60%;
  height: 120px;
}

Click to item to toggle size

Edit this demo or vanilla JS demo on CodePen

Web fonts

Like images, unloaded web fonts can throw off Isotope. To resolve this, trigger layout after fonts have been loaded. Both Typekit and Google WebFont Loader provide font events to control scripts based on how fonts are loaded.

Typekit

Try the script below when using Isotope on a page with Typekit. This will trigger Isotope when the document is ready and again when fonts have loaded. Be sure to remove Typekit’s default script, try{Typekit.load();}catch(e){}.

var $grid;

function triggerIsotope() {
  // don't proceed if $grid has not been selected
  if ( !$grid ) {
    return;
  }
  // init Isotope
  $grid.isotope({
    // options
  });
}
// trigger Isotope on document ready
$(function(){
  $grid = $('.grid');
  triggerIsotope();
});
// trigger Isotope when fonts have loaded
Typekit.load({
  active: triggerIsotope,
  inactive: triggerIsotope
});
// or with vanilla JS
var grid, iso;

function triggerIsotope() {
  // don't proceed if doc isn't ready
  if ( !grid ) {
    return;
  }
  // init Isotope
  iso = new Isotope( grid, {
    // options
  });
}
// initialize Isotope on document ready
document.addEventListener( 'DOMContentLoaded', function() {
  var grid = document.querySelector('.grid');
  triggerIsotope();
});
// trigger Isotope when fonts have loaded
Typekit.load({
  active: triggerIsotope,
  inactive: triggerIsotope
});

Issues

Reduced test cases

Creating a reduced test case is the best way to debug problems and report issues. Read CSS Tricks on why they’re so great.

Create a reduced test case for Isotope by forking any one of the CodePen demos from these docs.

Creating a reduced test case is the best way to get your issue addressed. They help you point out the problem. They help us debug the problem. They help others understand the problem.

Submitting issues

Report issues on GitHub. Make sure to include a reduced test case. Without a reduced test case, your issue may be closed.

Browser support

Isotope v3 supports IE10+, Android 4+, Safari for iOS 5+, Firefox 16+, and Chrome 12+.

For IE8+ and Android 2.3 support, try Isotope v2.

Upgrading from v2

Isotope v3 dropped browser support for IE8, IE9, and Android 2.3. Nearly all options, methods, and code for Isotope v2 is backwards compatibile with Isotope v3.

See Isotope releases on GitHub for detailed version-by-version changelog.