- Overview
- Documents
What is MixItUp?
MixItUp is a jQuery plugin providing animated filtering and sorting. Great for managing any categorised or ordered content like portfolios, galleries and blogs, MixItUp can also function as a powerful tool for engaging application UI and data-visualisation.
Why MixItUp?
MixItUp plays nice with your existing HTML and CSS, making it a great choice for responsive layouts.
MixItUp works with your layout. Want to use percentages, media queries, inline-block, CSS3 columns or even flex box? No problem.
Core Features
- Filter and sort elements with CSS3-optimised animations
- Build on top of your existing percentage-based responsive layouts and media queries
- Control filtering and sorting via a simple clickable interface or build more complex custom UI via an extensive API
- Customise your animations with CSS3 transforms and easing
- Add and remove elements in real time via an Ajax-friendly API
- Perform simultaneous filter, sort, and layout change operations
Source: mixitup.kunkalabs.com
1. INCLUDE JS FILES
<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script> <script src="http://cdn.jsdelivr.net/jquery.mixitup/latest/jquery.mixitup.min.js"></script>
2. HTML
Build your container:
<div id="Container"> <div class="mix category-1" data-my-order="1"> ... </div> <div class="mix category-1" data-my-order="2"> ... </div> <div class="mix category-2" data-my-order="3"> ... </div> <div class="mix category-2" data-my-order="4"> ... </div> </div>
Build your filter controls:
<button class="filter" data-filter=".category-1">Category 1</button> <button class="filter" data-filter=".category-2">Category 2</button>
Build your sort controls:
<button class="sort" data-sort="my-order:asc">Ascending Order</button> <button class="sort" data-sort="my-order:desc">Descending Order</button>
3. CSS
Hide target elements:
#Container .mix{ display: none; }
4. JAVASCRIPT
$(function(){ $('#Container').mixItUp(); });
5. OPTIONS
The configuration object is organized into several nested object literals of related properties. The entire object with all default values is listed below.
{ animation: { enable: true, effects: 'fade scale', duration: 600, easing: 'ease', perspectiveDistance: '3000', perspectiveOrigin: '50% 50%', queue: false, queueLimit: 1, animateChangeLayout: false, animateResizeContainer: true, animateResizeTargets: false, staggerSequence: false, reverseOut: false }, callbacks: { onMixLoad: false, onMixStart: false, onMixEnd: false, onMixFail: false, onMixBusy: false }, controls: { enable: true, live: false, toggleFilterButtons: false, toggleLogic: 'or', activeClass: 'active' }, layout: { display: 'inline-block', containerClass: '', containerClassFail: 'fail' }, load: { filter: 'all', sort: false }, selectors: { target: '.mix', filter: '.filter', sort: '.sort' } }
5. METHODS
instantiate
.mixItUp([configurationObject])
Instantiate MixItUp via a jQuery object.
Parameters | configurationObject |
---|---|
Type | Object |
Default | null |
Description | See Configuration Object |
This is the first and most important method of any MixItUp project and allows us to turn a DOM element into a MixItUp container.
With no parameters, MixItUp will be instantiated with the default configuration options. For advanced configuration, any number of options may be passed as an object literal. See Configuration Object.
$('#Container').mixItUp();
Instantiate MixItUp on the element with ID "Container", with its default configuration options
$('#Container').mixItUp({ animation: { effects: 'fade translateZ(500px)', duration: 300 }, selectors: { target: 'li' } });
Instantiate MixItUp with customized configuration options
filter
.mixItUp('filter', filterCommand [,animate] [,callback])
Filter the container to show or hide target elements.
Parameters | filterCommand | animate | callback |
---|---|---|---|
Type | String/Object/Function | Boolean | Function |
Default | - | true | null |
Description | A selector string, function or object against which to match desired target elements. | A boolean indicating whether to animate the filtering operation (asynchronously), or perform it instantly (synchronously). | An optional callback function to be called after the filter operation has completed. |
The filter command most commonly takes the form of a CSS selector string targeting the desired elements to show.
It may also take the form of a jQuery object, DOM element, or function. See jQuery’s .filter() documentation for more information.
$('#Container').mixItUp('filter', '.category-1');
Show target elements with the class "category-1"
$('#Container').mixItUp('filter', '.category-2', false);
Show target elements with the class "category-2", with no animation.
$('#Container').mixItUp('filter', $myCollection, function(state){ // callback function });
Show target elements matching a jQuery object, and call a callback function on completion.
This method is a short-hand for .mixItUp('multiMix', {filter: filterCommand})
sort
Sort the target elements by one or more arbitrary attributes or their order in the DOM.
.mixItUp('sort', sortCommand [,animate] [,callback])
Parameters | sortCommand | animate | callback |
---|---|---|---|
Type | String | Boolean | Function |
Default | - | true | null |
Description | A sort string made up of two colon-separated parts as follows: 'attribute-name:order' | A boolean indicating whether to animate the filtering operation (asynchronously), or perform it instantly (synchronously). | An optional callback function to be called after the filter operation has completed. |
The sort command is a space-separated string of colon-separated pairs. The first part of each pair is the name of the data attribute to sort by, and the second part of the pair is the order to sort by (asc or desc).
Commonly only one pair is passed to sort by a single attribute. However, any number of pairs may be passed to sort by multiple attributes in order of priority.
The second part of each pair is optional as ascending order is assumed.
The values random and default (the elements’ original order in the DOM) are also accepted.
$('#Container').mixItUp('sort', 'name:asc');
Sort target elements by the value of their "data-name" attributes, in ascending order.
$('#Container').mixItUp('sort', 'random', false);
Sort target elements by a random order, with no animation.
$('#Container').mixItUp('sort', 'age:desc name:asc', function(state){ // callback function });
Sort target elements first by their "data-age" attribute, and then by "data-name". Call a callback function when complete.
This method is a short-hand for .mixItUp('multiMix', {sort: sortCommand})
changeLayout
.mixItUp('changeLayout', layoutCommand [,animate] [,callback])
Change the layout of the container by changing the value of the CSS “display” property for target elements (e.g. block or inline-block), and/or applying a class to the container.
Parameters | layoutCommand | animate | callback |
---|---|---|---|
Type | String/Object | Boolean | Function |
Default | - | true | null |
Description | A string containing the desired display value for target elements, and (as an object) also an optional class to be applied to the container. | A boolean indicating whether to animate the filtering operation (asynchronously), or perform it instantly (synchronously). | An optional callback function to be called after the filter operation has completed. |
When passed as a string, the layout command sets the value of the CSS “display” property for target elements:
$('#Container').mixItUp('layoutChange', 'block');
Change the layout by changing target elements to "display: block"
$('#Container').mixItUp('layoutChange', { display: 'block', containerClass: 'list' }, function(state){ // callback function });
Change the target display value, add the class "list" to the container, and call a callback function when complete.
This method is a short-hand for .mixItUp('multiMix', {layoutChange: layoutCommand})
multiMix
.mixItUp('multiMix', multiMixObject [,animate] [,callback])
Perform simultaneous filter, sort, and layoutChange operations.
Parameters | multiMixObject | animate | callback |
---|---|---|---|
Type | Object | Boolean | Function |
Default | - | true | null |
Description | The multiMixObject contains individual properties for the filter, sort and layoutChange methods and their respective commands. Any or all of these properties may be passed with the same syntax as the individual method. | A boolean indicating whether to animate the filtering operation (asynchronously), or perform it instantly (synchronously). | An optional callback function to be called after the filter operation has completed. |
$('#Container').mixItUp('multiMix', { filter: '.category-1, .category-2', sort: 'name:asc', changeLayout: { containerClass: 'flex' } });
Perform filter, sort and layoutChange operations in a single animation.
prepend
.mixItUp('prepend', elements [,multiMixObject] [,callback])
Insert an element or collection of elements into the container, before all existing target elements.
Parameters | elements | multiMixObject | callback |
---|---|---|---|
Type | Object | Object | Function |
Default | - | null | null |
Description | A jQuery object collection of one or more elements to insert, or a single DOM element. | A multiMix object containing instructions about what to do after the insertion of elements. | An optional callback function to be called after elements have been inserted, or if applicable, after the multiMix operation has completed. |
If no multiMix object is passed, elements are inserted and MixItUp is refreshed. However, elements remain hidden until a subsequent filter operation is performed.
This method is recommended over prepending elements into the container manually (via native DOM methods) as it prompts a “refresh”, updating MixItUp’s sorting and filtering arrays. It also ensures that white space is maintained between inserted elements, which is vital for inline-block grids.
$('#Container').mixItUp('prepend', $myElement, {filter: '.category-1'})
Prepend an element into the container via a jQuery object, and show all elements with the class "category-1"
This method is a short-hand for .mixItUp('insert', 0, elements)
append
.mixItUp('append', elements, [,multiMixObject] [,callback])
Insert an element or collection of elements into the container, after all existing target elements.
Parameters | elements | multiMixObject | callback |
---|---|---|---|
Type | Object | Object | Function |
Default | - | null | null |
Description | A jQuery object collection of one or more elements to insert, or a single DOM element. | A multiMix object containing instructions about what to do after the insertion of elements. | An optional callback function to be called after elements have been inserted, or if applicable, after the multiMix operation has completed. |
If no multiMix object is passed, elements are inserted and MixItUp is refreshed. However, elements remain hidden until a subsequent filter operation is performed.
This method is recommended over appending elements into the container manually (via native DOM methods) as it prompts a “refresh”, updating MixItUp’s sorting and filtering arrays. It also ensures that white space is maintained between inserted elements, which is vital for inline-block grids.
$('#Container').mixItUp('append', $newObject, {filter: '#NewObject'})
Append an element into the container via a jQuery object, and show it via its ID.
This method is a short-hand for: .mixItUp('insert', self._state.totalTargets, elements)
insert
.mixItUp('insert', index, elements, [,multiMixObject] [,callback])
Insert an element or collection of elements into the container at an arbitrary index.
Parameters | index | elements | multiMixObject | callback --- | --- | --- | --- Type | Number | Object | Object | Function Default | - | - |null | null Description | The index of the target element before which to insert elements. | A jQuery object collection of one or more elements to insert, or a single DOM element. | A multiMix object containing instructions about what to do after the insertion of elements. | An optional callback function to be called after elements have been inserted, or if applicable, after the multiMix operation has completed.
If no multiMix object is passed, elements are inserted and MixItUp is refreshed. However, elements remain hidden until a subsequent filter operation is performed.
This method is recommended over appending elements into the container manually (via native DOM methods) as it prompts a “refresh”, updating MixItUp’s sorting and filtering arrays. It also ensures that white space is maintained between inserted elements, which is vital for inline-block grids.
$('#Container').mixItUp('insert', 5, $('<div class="mix category-1"></div>'), {filter: 'all'})
Create and insert a new object into the container before the 5th target element, and show all elements.
isMixing
.mixItUp('isMixing')
This is method returns a boolean and is used to find out if a filter, sort, or layoutChange operation is in progress. It can be useful for custom user-interfaces where queuing is not enabled.
if(!$('#Container').mixItUp('isMixing')){ // If container is not busy }
Do something only if an operation is not currently in progress.
isLoaded
.mixItUp('isLoaded')
This method returns a boolean and is used to find out if MixItUp has been instantiated on a particular jQuery object. It is useful for debugging and also for ajax situations where MixItUp containers may be created dynamically.
var $container = $('#Container'); if(!$container.mixItUp('isLoaded')){ $container.mixItUp(); }
Instantiate MixItUp on the container, only if it has not already been instantiated.
setOptions
.mixItUp('setOptions', configurationObject)
Set or change configuration option in real time, after MixItUp has instantiated.
Parameters | configurationObject |
---|---|
Type | Object |
Default | null |
Description | See Configuration Object |
Any options changed will be reflected when the next operation is performed.
$('#Container').mixItUp('setOptions', { animation: { effects: 'fade scale translateX stagger' }, callbacks: { onMixEnd: function(){ // do something } } });
Change the animation effects, and add a callback function.
$('#Container').mixItUp('setOptions', { animation: { enable: false }, callbacks: { onMixEnd: null } });
Disable effects, and remove any existing callback function
getOption
.mixItUp('getOption', stringKey)
Retrieve the value of any configuration option via its key.
Parameters | stringKey |
---|---|
Type | String |
Description | The key of the configuration option you wish to retrieve the value for. Since all configuration options are nested properties of the configuration object, the string must take the form 'parentObject.propertyName'. |
var duration = $('#Container').mixItUp('getOption', 'animation.duration'); alert(duration); // alerts 600
Retrieve the value of the "duration" animation option.
getState
.mixItUp('getState')
Retrieve the State Object.
var state = $('#Container').mixItUp('getState'); alert(state.activeFilter); // alerts '.category-1'
Save the state object to a variable and find the active filter
destroy
mixItUp('destroy', hideAll)
Unbind all handlers, and delete the instance of MixItUp from the memory.
Parameters | hideAll |
---|---|
Type | Boolean |
Default | false |
Description | A boolean indicating whether to also remove the inline “display” style from all target elements added by MixItUp, thus hiding any elements currently shown. |
$('#Container').mixItUp('destroy');
Destroy the instance of MixItUp
$('#Container').mixItUp('destroy', true);
7. EVENTS
MixItUp containers trigger the following events which may be bound with custom event handlers:
- mixLoad - Triggered when MixItUp first loads and any loading animation has completed.
- mixStart - Triggered immediately after any MixItUp operation is requested and before animations have begun.
- mixEnd – Triggered after any MixItUp operation has completed, and the state object has been updated.
- mixFail - Triggered after a filter operation when no target elements match the requested filter command.
- mixBusy - Triggered if animation queuing is disabled and a MixItUp operation is requested while another operation is in progress.
Binding events may be preferable to setting single callback functions via the configuration object if conditional behaviour is required or you wish to add and remove event handlers dynamically.
MixItUp events may be bound as follows using jQuery. The state object is passed as the second parameter after the event object. For `mixStart`, a futureState object is passed as the third parameter.
$('#Container').on('mixEnd', function(e, state){ console.log(state.totalShow+' elements match the current filter'); });