- Overview
- Documents
- Demos
Isotope: An exquisite jQuery plugin for magical layouts
Features
- Layout modes: Intelligent, dynamic layouts that can’t be achieved with CSS alone.
- Filtering: Hide and reveal item elements easily with jQuery selectors.
- Sorting: Re-order item elements with sorting. Sorting data can be extracted from just about anything.
- Interoperability: features can be utilized together for a cohesive experience.
- Progressive enhancement: Isotope’s animation engine takes advantage of the best browser features when available — CSS transitions and transforms, GPU acceleration — but will also fall back to JavaScript animation for lesser browsers.
Getting started
HTML
Isotope works on a container element with a group of similar child items.
<div id="container"> <div class="item">...</div> <div class="item w2">...</div> <div class="item">...</div> ... </div>
Include the Isotope script in your site.
<script src="/path/to/isotope.pkgd.min.js"></script>
CSS
All sizing of items is handled by your CSS.
.item { width: 25%; } .item.w2 { width: 50%; }
Initialize with JavaScript
Initialize an Isotope instance as a jQuery plugin: $('#container').isotope().
var $container = $('#container'); // init $container.isotope({ // options itemSelector: '.item', layoutMode: 'fitRows' });
Options
- animationEngine (String): 'best-available'
Determines the jQuery method to apply styles, .css() or .animate(). Useful for relying on CSS transitions to handle animation.
Values
- 'best-available': if browser supports CSS transitions, Isotope uses .css(). If not, falls back to using .animate().
- 'css': Isotope uses .css()
- 'jquery': Isotope uses .animate()
- animationOptions (Object): { queue: false, duration: 800 }
When jQuery is the animation engine (see above), these options will be used in .animate(). See thejQuery API for animate options for details.
Example
$('#container').isotope({ animationOptions: { duration: 750, easing: 'linear', queue: false } });
- containerClass (String): 'isotope'
The class applied to the container element.
- containerStyle (Object): { position: 'relative', overflow: 'hidden' }
CSS styles applied to the container element. Relative positioning enables absolute positioning on child items. Hidden overflow ensures that filtered items that lie outside the container do not interfer with subsequent content.
- filter: Selector
Setting a filter with show item elements that match the selector, and hide elements that do not match. See docs on filering for more details.
Values
- '*' or '' (an empty string): Shows all item elements
- getSortData: Object
An object containing one or several methods to retrieve data for Sorting. The methods receive one parameter ($elem in the example below) which is a jQuery object representing each item element. The methods need to return a value.
Example
$('#container').isotope({ getSortData : { symbol : function( $elem ) { return $elem.attr('data-symbol'); }, number : function( $elem ) { return parseInt( $elem.find('.number').text(), 10 ); }, name : function ( $elem ) { return $elem.find('.name').text(); } } });
- hiddenClass (String): 'isotope-hidden'
The class applied to item elements hidden by Filtering.
- hiddenStyle (Object): { opacity : 0, scale : 0.001 }
The style applied to item elements hidden by Filtering.
- itemClass (String): 'isotope-item'
The class applied to item elements.
- itemPositionDataEnabled (Boolean):false
When enabled, the position of item elements will exposed as data, which you can retrieve with jQuery’s data method with 'isotope-item-position' name space. Position is return as an object withx and y;
Example
$('#container').isotope({ itemSelector: '.element', itemPositionDataEnabled: true }) // log position of each item .find('.element').each(function(){ var position = $(this).data('isotope-item-position'); console.log('item position is x: ' + position.x + ', y: ' + position.y ); });
- itemSelector (Selector)
Restricts Isotope item elements to selector.
- layoutMode (String): 'masonry'
- onLayout (Function)
Similiar to a callback, onLayout is a function that will be triggered after every time an Isotope instance runs through its layout logic.
$('#container').isotope({ onLayout: function( $elems, instance ) { // `this` refers to jQuery object of the container element console.log( this.height() ); // callback provides jQuery object of laid-out item elements $elems.css({ background: 'blue' }); // instance is the Isotope instance console.log( instance.$filteredAtoms.length ); } });
- resizable (Boolean): true
Triggers layout logic when browser window is resized.
- resizesContainer (Boolean): true
Isotope will set the height (for vertical layout modes) or width (for horizontal layout modes) of the container after layout. If resizesContainer is set to false, be sure to set a size for the container in your CSS, so it doesn’t collapse when Isotope is triggered.
- sortAscending (Boolean): true
Used with sorting. If true, items are sorted ascending: “1, 2, 3” or “A, B, C…”. If false, items are sorted descending “Z, Y, X” or “9, 8, 7…”.
- sortBy (String)
The property name of the method within the getSortData option to sort item elements.
Values
- 'original-order' Sorts item elements by their original order.
- transformsEnabled (Boolean): true
Isotope uses CSS3 transforms to position item elements, when available in the browser. SettingtransformsEnabled to false will disable this feature so all browsers use top/left absolute positioning.
Additional CSS
If you do disable transforms, but still want to use CSS transitions, you’ll need add the following CSS:
.isotope .isotope-item { -webkit-transition-property: top, left, opacity; -moz-transition-property: top, left, opacity; -ms-transition-property: top, left, opacity; -o-transition-property: top, left, opacity; transition-property: top, left, opacity; }
visibleStyle
- visibleStyle (Object): { opacity : 1, scale : 1 }
The style applied to item elements made visible by Filtering.
Layout-specific options
In addition the general options listed above, certain layout modes each have their own options. In order to avoid conflict, these options are set with an option that matches the name of the layout mode.
See docs on layout modes for each layout mode’s available options.
For example, if your layout switched from masonry to cellsByRow:
$('#container').isotope({ masonry: { columnWidth: 120 }, cellsByRow: { columnWidth: 220, rowHeight: 220 } });
Methods
Isotope offers several methods to extend functionality. Isotope’s methods follow the jQuery UI pattern.
$('#container').isotope( 'methodName', [optionalParameters] )
addItems
.isotope( 'addItems', $items, callback )
Adds item elements to the pool of item elements of the container, but does not sort, filter or layout. See Adding items for more details. The argument within the callback is the group of elements that were added.
appended
.isotope( 'appended', $items, callback )
Adds item elements via addItems method, then triggers layout just for those new elements. Useful for Infinite Scroll. See Adding items for more details.
destroy
.isotope( 'destroy' )
Removes Isotope functionality completely. Returns element back to pre-init state.
insert
.isotope( 'insert', $items, callback )
Appends items elements to container, adds items to via addItems method, and then triggers reLayoutmethod so new elements are properly filtered, sorted and laid-out. See Adding items for more details.
layout
.isotope( 'layout', $items, callback )
Positions specified item elements in layout.
layout will only position specified elements, and those elements will be positioned at the end of layout. Whereas reLayout will position all elements in the Isotope widget.
option
.isotope( 'option', options )
Sets options for plugin instance. Unlike passing options through .isotope(), using the optionmethod will not trigger layout.
// sets multiple options .isotope( 'option', { layoutMode: 'fitRows', filter: '.my-filter' } )
reLayout
.isotope( 'reLayout', callback )
Resets layout properties and lays-out every item element.
reloadItems
.isotope( 'reloadItems' )
Re-collects all item elements in their current order in the DOM. Useful for prepending.
remove
.isotope( 'remove', $items, callback )
Removes specified item elements from Isotope widget and the DOM.
shuffle
.isotope( 'shuffle', callback )
Shuffles order of items. Sets sortBy option to 'random'.
updateSortData
.isotope( 'updateSortData', $items )
Updates the sorting data on specified item elements. This method is useful if the data within an item is changed dynamically after Isotope has been initialized.
Layout modes
- Horizontal layouts
- cellsByColumn
- cellsByRow
- fitColumns
- fitRows
- masonry
- masonryHorizontal
- straightAcross
- straightDown
More information at: http://isotope.metafizzy.co/v1/docs/introduction.html