Appendix

imagesLoaded

Unloaded images can throw off Isotope layouts and cause item elements to overlap. imagesLoaded resolves this issue. imagesLoaded works by triggering a callback after all child images have been loaded.

// initialize Isotope after all images have loaded
var $container = $('#container').imagesLoaded( function() {
  $container.isotope({
    // options
  });
});
// or with vanilla JS
var container = document.querySelector('#container');
var iso;
// initialize Isotope after all images have loaded
imagesLoaded( container, function() {
  iso = new Isotope( container, {
    // options
  });
});

Or initialize Isotope first, then trigger layout after images have loaded.

// initialize Isotope
var $container = $('#container').isotope({
  // options
});
// layout Isotope again after all images have loaded
$container.imagesLoaded( function() {
  $container.isotope('layout');
});
// or with vanilla JS
// initialize Isotope
var iso = new Isotope( container, {
  // options
});
// layout Isotope again after all images have loaded
imagesLoaded( container, function() {
  iso.layout();
});

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 $container;

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

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

Support

CodersClan has a dedicated support forum for Isotope, where you can get personal support from experienced developers.

Get support

Submitting issues

Submit bugs and issues to the GitHub issue tracker.

Reduced test case required

All bug reports and problem issues require a reduced test case. Create one by forking any one of the CodePen examples from these docs.

Providing a reduced test case is the best way to get your issue addressed. Without a reduced test case, your issue may be closed.

Upgrading from v1

New features

Changes

Upgrades to masonry layout mode

RequireJS

Isotope supports RequireJS.

You can require isotope.pkgd.js.

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

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( '#container', {
    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() {
      // make Isotope a jQuery plugin
      $.bridget( 'isotope', Isotope );
      // now you can use $().isotope()
      $('#container').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( '#container', {...});
});

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 ) {
    // make Isotope a jQuery plugin
    $.bridget( 'isotope', Isotope );
    // now you can use $().isotope()
    $('#container').isotope({...});
});

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="isotope">
  <!-- items have item-content children element -->
  <div class="item">
    <div class="item-content"></div>
  </div>
  ...
/* item is invisible, but used for layout
item-content is visible, and transitions size */
.animate-item-size-demo .item,
.animate-item-size-demo .item-content {
  width: 60px;
  height: 60px;
}
.animate-item-size-demo .item-content {
  background: #09D;
  transition: width 0.4s, height 0.4s;
  /* -webkit-transition -moz, etc, too */
}
/* both item and item content change size */
.animate-item-size-demo .item.is-expanded,
.animate-item-size-demo .item.is-expanded .item-content {
  width: 180px;
  height: 120px;
}

Click to item to toggle size

Edit this example or example with vanilla JS 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.

#animate-item-size-responsive .item {
  width: 20%;
  height: 60px;
}

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

Click to item to toggle size

Edit this example or the example with vanilla JS on CodePen

Component libraries

Isotope includes several vanilla JS component libraries. You might have seen these used in the example code. You can use some of these libraries in your own code.

docReady

docReady triggers initialization logic when the document is ready, just like jQuery's $(document).ready(). docReady is used to initialize all the demos in these docs.

docReady( function() {
  // document is ready, let's do some fun stuff!
  var container = document.querySelector('#container');
  var iso = new Isotope( container );
});

eventie

Eventie makes event binding in IE8 legit.

var elem = document.querySelector('#my-elem');
function onElemClick( event ) {
  console.log( event.type + ' just happened on #' + event.target.id );
  // -> click just happened on #my-elem
}
// bind it
eventie.bind( elem, 'click', onElemClick );
// unbind it
eventie.unbind( elem, 'click', onElemClick );

Extra examples

Additional resources