Help

Reporting bugs and issues

Please read my Issues Agreement and then report bugs and issues on GitHub.

Additional resources

Unloaded media

Most layout modes (i.e masonry, fitRows) need to measure the size of each item to appropriately account for its space in the layout. Unloaded media files like images and @font-face fonts can throw off layout and cause item elements to overlap one another. Ideally, Isotope layouts should be initialized after all inner content has loaded.

Images

Inline dimensions

For images, the best method is to specify the width and height of images inline.

<img src="img-file.jpg" width="280" height="160" />

If you’re using a PHP-based CMS, you can use the getimagesize function.

imagesLoaded plugin

The next best solution is to use the imagesLoaded plugin included with Isotope. It’s a small plugin that finds all the images in a context, and fires a callback function once all the images have loaded.

var $container = $('#container');

$container.imagesLoaded( function(){
  $container.isotope({
    // options...
  });
});

$(window).load()

Another solution is to initialize Isotope inside $(window).load() instead of $(document).ready(). This will trigger Isotope after all the media on the page has loaded.

$(window).load(function(){
  $('#container').isotope({
    // options...
  });
});

@font-face fonts

Both Typekit and Google WebFont Loader provide font events to control scripts based on how fonts are loaded.

Problems with CSS transforms

As the browser implementations of CSS tranforms are still a work-in-progress, they can cause buggy behavoir with other types of dynamic content.

Disabling transforms

Set transformsEnabled to false. This is an easy step to take when troubleshooting.

$('#container').isotope({
  // options...
  transformsEnabled: false
});

Getting item position

CSS transforms will break previous patterns for getting the position of an item. See the itemPositionDataEnabled option for a stop-gap.

Accessing the instance

Similar to jQuery UI, Isotope stores a instance containing properties, settings and methods with jQuery.data. You can access the instance with the 'isotope' namespace.

var $container = $('#container');

// initialize Isotope instance
$container.isotope({
  // options...
});

// get Isotope instance
var isotopeInstance = $container.data('isotope');
isotopeInstance.options; // options
isotopeInstance.$filteredAtoms; // jQuery object of filtered & sorted item elements
isotopeInstance.masonry.columnWidth; // Layout mode specific properties

CSS transforms in Opera

Currently, using CSS transforms in Opera distorts text rendering. To avoid this issue, the default value of transformsEnabled is set to for Opera.

Also note that the recommended transition CSS uses left/top properties for Opera.

Infinite Scroll with filtering or sorting

I recommend against using Infinite Scroll with filtering or sorting. This combination produces a unnecessarily complex user interaction that will frustrate your users. New content gets added, but part of it might be hidden. There is no way for the user to tell what gets hidden or re-arranged when Infinite Scroll adds more content. Exercise moderation with your Isotope implementation.

If you do plan on implementing Infinite Scroll with filtering or sorting (which is a bad idea), use the insert method instead of appended.

Poor type rendering in WebKit

Type rendering may appear poor in WebKit browsers like Chrome and Safari. This is because of Isotope’s activation of hardware acceleration. A solution is to add add a matching background to the item elements. See more: dropshado.ws - Resolving anti-aliasing on WebKit hardware-accelerated elements. Another solution is to disable transforms.

First item breaks Masonry layout

With Masonry layout mode If you run into an issue where you re-size the first item, and all the rest of the items no longer fit together in the grid, you most likely need to set columnWidth option. Without columnWidth set, the Masonry layout mode will use the width of the first item for the size of its columns.

$('#container').isotope(
  masonry: {
    columnWidth: 220
  }
});

Right-to-left layouts

Isotope can be modified to support right-to-left layouts for languages like Hebrew and Arabic.

See test: Right to left

You’ll need to make the following changes:

JavaScript for right-to-left support

// modify Isotope's absolute position method
$.Isotope.prototype._positionAbs = function( x, y ) {
  return { right: x, top: y };
};

// initialize Isotope
$('#container').isotope({
  transformsEnabled: false
  // other options...
});

CSS for right-to-left support

.isotope .isotope-item {
  -webkit-transition-property: right, top, -webkit-transform, opacity;
     -moz-transition-property: right, top, -moz-transform, opacity;
      -ms-transition-property: right, top, -ms-transform, opacity;
       -o-transition-property: right, top, -o-transform, opacity;
          transition-property: right, top, transform, opacity;
}

Preventing clicks on filtered items

The recommended CSS for filtering includes pointer-events: none for .isotope-hidden. Unfortunately, Opera and Internet Explorer still let click events propagate with this style in place. But you can still dismiss click events in your click handler by checking to see if the element or element’s parent is a filtered item.

See test: Unclickable filtered

$('.item a').click(function(){
  var $this = $(this);
  // back out if hidden item
  if ( $this.parents('.isotope-item').hasClass('isotope-hidden') ) {
    return;
  }
  // otherwise, continue to do stuff...
  console.log('item was clicked');
});