mixitup.Mixer

The mixitup.Mixer class is used to hold discreet, user-configured instances of MixItUp on a provided container element.

Mixer instances are returned whenever the mixitup() factory function is called, which expose a range of methods enabling API-based filtering, sorting, insertion, removal and more.

show()

.show()

Type Name Description
@return Promise.<mixitup.State>

A shorthand method for .filter('all'). Shows all targets in the container.

Example: Showing all targets

mixer.show()
    .then(function(state) {
        console.log(state.totalShow === state.totalTargets); // true
    });
hide()

.hide()

Type Name Description
@return Promise.<mixitup.State>

A shorthand method for .filter('none'). Hides all targets in the container.

Example: Hiding all targets

mixer.hide()
    .then(function(state) {
        console.log(state.totalShow === 0); // true
        console.log(state.totalHide === state.totalTargets); // true
    });
isMixing()

.isMixing()

Type Name Description
@return boolean

Returns a boolean indicating whether or not a MixItUp operation is currently in progress.

Example: Checking the status of a mixer

mixer.sort('random', function() {
    console.log(mixer.isMixing()) // false
});

console.log(mixer.isMixing()) // true
filter()

.filter(selector [, animate] [, callback])

Type Name Description
@param string, HTMLElement, Array.<HTMLElement> selector

Any valid CSS selector (i.e. '.category-a'), or the values 'all' or 'none'. The filter method also accepts a reference to single target element or a collection of target elements to show.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Filters all targets in the container by a provided selector string, or the values 'all' or 'none'. Only targets matching the selector will be shown.

Example 1: Filtering targets by a class selector

mixer.filter('.category-a')
    .then(function(state) {
        console.log(state.totalShow === containerEl.querySelectorAll('.category-a').length); // true
    });

Example 2: Filtering targets by an attribute selector

mixer.filter('[data-category~="a"]')
    .then(function(state) {
        console.log(state.totalShow === containerEl.querySelectorAll('[data-category~="a"]').length); // true
    });

Example 3: Filtering targets by a compound selector

// Show only those targets with the classes 'category-a' AND 'category-b'

mixer.filter('.category-a.category-c')
    .then(function(state) {
        console.log(state.totalShow === containerEl.querySelectorAll('.category-a.category-c').length); // true
    });

Example 4: Filtering via an element collection

var collection = Array.from(container.querySelectorAll('.mix'));

console.log(collection.length); // 34

// Filter the collection manually using Array.prototype.filter

var filtered = collection.filter(function(target) {
   return parseInt(target.getAttribute('data-price')) > 10;
});

console.log(filtered.length); // 22

// Pass the filtered collection to MixItUp

mixer.filter(filtered)
   .then(function(state) {
       console.log(state.activeFilter.collection.length === 22); // true
   });
toggleOn()

.toggleOn(selector [, animate] [, callback])

Type Name Description
@param string selector

Any valid CSS selector (i.e. '.category-a')

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Adds an additional selector to the currently active filter selector, concatenating as per the logic defined in controls.toggleLogic.

Example: Toggling on a filter selector

console.log(mixer.getState().activeFilter.selector); // '.category-a'

mixer.toggleOn('.category-b')
    .then(function(state) {
        console.log(state.activeFilter.selector); // '.category-a, .category-b'
    });
toggleOff()

.toggleOff(selector [, animate] [, callback])

Type Name Description
@param string selector

Any valid CSS selector (i.e. '.category-a')

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Removes a selector from the active filter selector.

Example: Toggling off a filter selector

console.log(mixer.getState().activeFilter.selector); // '.category-a, .category-b'

mixer.toggleOff('.category-b')
    .then(function(state) {
        console.log(state.activeFilter.selector); // '.category-a'
    });
sort()

.sort(sortString [, animate] [, callback])

Type Name Description
@param string, Array.<HTMLElement> sortString

A valid sort string (e.g. 'default', 'published-date:asc', or 'random'). The sort method also accepts an array of all target elements in a user-defined order.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Sorts all targets in the container according to a provided sort string.

Example 1: Sorting by the default DOM order

// Reverse the default order of the targets

mixer.sort('default:desc')
    .then(function(state) {
        console.log(state.activeSort.attribute === 'default'); // true
        console.log(state.activeSort.order === 'desc'); // true
    });

Example 2: Sorting by a custom data-attribute

// Sort the targets by the value of a `data-published-date` attribute

mixer.sort('published-date:asc')
    .then(function(state) {
        console.log(state.activeSort.attribute === 'published-date'); // true
        console.log(state.activeSort.order === 'asc'); // true
    });

Example 3: Sorting by multiple attributes

// Sort the targets by the value of a `data-published-date` attribute, then by `data-title`

mixer.sort('published-date:desc data-title:asc')
    .then(function(state) {
        console.log(state.activeSort.attribute === 'published-date'); // true
        console.log(state.activeSort.order === 'desc'); // true

        console.log(state.activeSort.next.attribute === 'title'); // true
        console.log(state.activeSort.next.order === 'asc'); // true
    });

Example 4: Sorting by random

mixer.sort('random')
    .then(function(state) {
        console.log(state.activeSort.order === 'random') // true
    });

Example 5: Sorting via an element collection

var collection = Array.from(container.querySelectorAll('.mix'));

// Swap the position of two elements in the collection:

var temp = collection[1];

collection[1] = collection[0];
collection[0] = temp;

// Pass the sorted collection to MixItUp

mixer.sort(collection)
    .then(function(state) {
        console.log(state.targets[0] === collection[0]); // true
    });
changeLayout()

.changeLayout(containerClassName [, animate] [, callback])

Type Name Description
@param string containerClassName

A layout-specific class name to add to the container.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Changes the layout of the container by adding, removing or updating a layout-specific class name. If animation.animateResizetargets is enabled, MixItUp will attempt to gracefully animate the width, height, and position of targets between layout states.

Example 1: Adding a new class name to the container

mixer.changeLayout('container-list')
     .then(function(state) {
         console.log(state.activeContainerClass === 'container-list'); // true
     });

Example 2: Removing a previously added class name from the container

mixer.changeLayout('')
     .then(function(state) {
         console.log(state.activeContainerClass === ''); // true
     });
dataset()

.dataset(dataset [, animate] [, callback])

Type Name Description
@param Array.<object> dataset

An array of objects, each one representing the underlying data model of a target to be rendered.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Updates the contents and order of the container to reflect the provided dataset, if the dataset API is in use.

The dataset API is designed for use in API-driven JavaScript applications, and can be used instead of DOM-based methods such as .filter(), .sort(), .insert(), etc. When used, insertion, removal, sorting and pagination can be achieved purely via changes to your data model, without the uglyness of having to interact with or query the DOM directly.

Example 1: Rendering a dataset

var myDataset = [
    {id: 1, ...},
    {id: 2, ...},
    {id: 3, ...}
];

mixer.dataset(myDataset)
    .then(function(state) {
        console.log(state.totalShow === 3); // true
    });

Example 2: Sorting a dataset

// Create a new dataset in reverse order

var newDataset = myDataset.slice().reverse();

mixer.dataset(newDataset)
    .then(function(state) {
        console.log(state.activeDataset[0] === myDataset[2]); // true
    });

Example 3: Removing an item from the dataset

console.log(myDataset.length); // 3

// Create a new dataset with the last item removed.

var newDataset = myDataset.slice().pop();

mixer.dataset(newDataset)
    .then(function(state) {
        console.log(state.totalShow === 2); // true
    });
multimix()

.multimix(multimixCommand [, animate] [, callback])

Type Name Description
@param object multimixCommand

An object containing one or more things to do

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Performs simultaneous filter, sort, insert, remove and changeLayout operations as requested.

Example 1: Performing simultaneous filtering and sorting

mixer.multimix({
    filter: '.category-b',
    sort: 'published-date:desc'
})
    .then(function(state) {
        console.log(state.activeFilter.selector === '.category-b'); // true
        console.log(state.activeSort.attribute === 'published-date'); // true
    });

Example 2: Performing simultaneous sorting, insertion, and removal

console.log(mixer.getState().totalShow); // 6

// NB: When inserting via `multimix()`, an object should be provided as the value
// for the `insert` portion of the command, allowing for a collection of elements
// and an insertion index to be specified.

mixer.multimix({
    sort: 'published-date:desc', // Sort the container, including any new elements
    insert: {
        collection: [newElementReferenceA, newElementReferenceB], // Add 2 new elements at index 5
        index: 5
    },
    remove: existingElementReference // Remove 1 existing element
})
    .then(function(state) {
        console.log(state.activeSort.attribute === 'published-date'); // true
        console.log(state.totalShow === 7); // true
    });
insert()

.insert(newElements [, index] [, animate], [, callback])

Type Name Description
@param HTMLElement, Array.<HTMLElement>, string newElements

A reference to a single element to insert, an array-like collection of elements, or an HTML string representing a single element.

@param number index

The index at which to insert the new element(s). 0 by default.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Inserts one or more new target elements into the container at a specified index.

To be indexed as targets, new elements must match the selectors.target selector ('.mix' by default).

Example 1: Inserting a single element via reference

console.log(mixer.getState().totalShow); // 0

// Create a new element

var newElement = document.createElement('div');
newElement.classList.add('mix');

mixer.insert(newElement)
    .then(function(state) {
        console.log(state.totalShow === 1); // true
    });

Example 2: Inserting a single element via HTML string

console.log(mixer.getState().totalShow); // 1

// Create a new element via reference

var newElementHtml = '<div class="mix"></div>';

// Create and insert the new element at index 1

mixer.insert(newElementHtml, 1)
    .then(function(state) {
        console.log(state.totalShow === 2); // true
        console.log(state.show[1].outerHTML === newElementHtml); // true
    });

Example 3: Inserting multiple elements via reference

console.log(mixer.getState().totalShow); // 2

// Create an array of new elements to insert.

var newElement1 = document.createElement('div');
var newElement2 = document.createElement('div');

newElement1.classList.add('mix');
newElement2.classList.add('mix');

var newElementsCollection = [newElement1, newElement2];

// Insert the new elements starting at index 1

mixer.insert(newElementsCollection, 1)
    .then(function(state) {
        console.log(state.totalShow === 4); // true
        console.log(state.show[1] === newElement1); // true
        console.log(state.show[2] === newElement2); // true
    });

Example 4: Inserting a jQuery collection object containing one or more elements

console.log(mixer.getState().totalShow); // 4

var $newElement = $('<div class="mix"></div>');

// Insert the new elements starting at index 3

mixer.insert(newElementsCollection, 3)
    .then(function(state) {
        console.log(state.totalShow === 5); // true
        console.log(state.show[3] === $newElement[0]); // true
    });
insertBefore()

.insertBefore(newElements, referenceElement [, animate] [, callback])

Type Name Description
@param HTMLElement, Array.<HTMLElement>, string newElements

A reference to a single element to insert, an array-like collection of elements, or an HTML string representing a single element.

@param HTMLElement referenceElement

A reference to an existing element in the container to insert new elements before.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Inserts one or more new elements before a provided reference element.

Example: Inserting a new element before a reference element

// An existing reference element is chosen at index 2

var referenceElement = mixer.getState().show[2];

// Create a new element

var newElement = document.createElement('div');
newElement.classList.add('mix');

mixer.insertBefore(newElement, referenceElement)
    .then(function(state) {
        // The new element is inserted into the container at index 2, before the reference element

        console.log(state.show[2] === newElement); // true

        // The reference element is now at index 3

        console.log(state.show[3] === referenceElement); // true
    });
insertAfter()

.insertAfter(newElements, referenceElement [, animate] [, callback])

Type Name Description
@param HTMLElement, Array.<HTMLElement>, string newElements

A reference to a single element to insert, an array-like collection of elements, or an HTML string representing a single element.

@param HTMLElement referenceElement

A reference to an existing element in the container to insert new elements after.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Inserts one or more new elements after a provided reference element.

Example: Inserting a new element after a reference element

// An existing reference element is chosen at index 2

var referenceElement = mixer.getState().show[2];

// Create a new element

var newElement = document.createElement('div');
newElement.classList.add('mix');

mixer.insertAfter(newElement, referenceElement)
    .then(function(state) {
        // The new element is inserted into the container at index 3, after the reference element

        console.log(state.show[3] === newElement); // true
    });
prepend()

.prepend(newElements [,animate] [,callback])

Type Name Description
@param HTMLElement, Array.<HTMLElement>, string newElements

A reference to a single element to insert, an array-like collection of elements, or an HTML string representing a single element.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Inserts one or more new elements into the container before all existing targets.

Example: Prepending a new element

// Create a new element

var newElement = document.createElement('div');
newElement.classList.add('mix');

// Insert the element into the container

mixer.prepend(newElement)
    .then(function(state) {
        console.log(state.show[0] === newElement); // true
    });
append()

.append(newElements [,animate] [,callback])

Type Name Description
@param HTMLElement, Array.<HTMLElement>, string newElements

A reference to a single element to insert, an array-like collection of elements, or an HTML string representing a single element.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Inserts one or more new elements into the container after all existing targets.

Example: Appending a new element

// Create a new element

var newElement = document.createElement('div');
newElement.classList.add('mix');

// Insert the element into the container

mixer.append(newElement)
    .then(function(state) {
        console.log(state.show[state.show.length - 1] === newElement); // true
    });
remove()

.remove(elements [, animate] [, callback])

Type Name Description
@param HTMLElement, Array.<HTMLElement>, string, number elements

A reference to a single element to remove, an array-like collection of elements, a selector string, or the index of an element to remove.

@param boolean [animate]

An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. true by default.

@param function [callback]

An optional callback function to be invoked after the operation has completed.

@return Promise.<mixitup.State> A promise resolving with the current state object.

Removes one or more existing target elements from the container.

Example 1: Removing an element by reference

var elementToRemove = containerEl.firstElementChild;

mixer.remove(elementToRemove)
     .then(function(state) {
         console.log(state.targets.indexOf(elementToRemove) === -1); // true
     });

Example 2: Removing a collection of elements by reference

var elementsToRemove = containerEl.querySelectorAll('.category-a');

console.log(elementsToRemove.length) // 3

mixer.remove(elementsToRemove)
     .then(function() {
         console.log(containerEl.querySelectorAll('.category-a').length); // 0
     });

Example 3: Removing one or more elements by selector

mixer.remove('.category-a')
     .then(function() {
         console.log(containerEl.querySelectorAll('.category-a').length); // 0
     });

Example 4: Removing an element by index

console.log(mixer.getState.totalShow); // 4

// Remove the element at index 3

mixer.remove(3)
     .then(function(state) {
         console.log(state.totalShow); // 3
         console.log(state.show[3]); // undefined
     });
getConfig()

.getConfig([stringKey])

Type Name Description
@param string [stringKey]

A “dot-notation” string key

@return *

Retrieves the the value of any property or sub-object within the current mixitup configuration, or the whole configuration object.

Example 1: retrieve the entire configuration object

var config = mixer.getConfig(); // Config { ... }

Example 2: retrieve a named sub-object of configuration object

var animation = mixer.getConfig('animation'); // ConfigAnimation { ... }

Example 3: retrieve a value of configuration object via a dot-notation string key

var effects = mixer.getConfig('animation.effects'); // 'fade scale'
configure()

.configure(config)

Type Name Description
@param object config

An object containing one of more configuration options.

@return void

Updates the configuration of the mixer, after it has been instantiated.

See the Configuration Object documentation for a full list of avilable configuration options.

Example 1: Updating animation options

mixer.configure({
    animation: {
        effects: 'fade translateX(-100%)',
        duration: 300
    }
});

Example 2: Removing a callback after it has been set

var mixer;

function handleMixEndOnce() {
    // Do something ..

    // Then nullify the callback

    mixer.configure({
        callbacks: {
            onMixEnd: null
        }
    });
};

// Instantiate a mixer with a callback defined

mixer = mixitup(containerEl, {
    callbacks: {
        onMixEnd: handleMixEndOnce
    }
});
getState()

.getState();

Type Name Description
@return mixitup.State An object reflecting the current state of the mixer.

Returns an object containing information about the current state of the mixer. See the State Object documentation for more information.

NB: State objects are immutable and should therefore be regenerated after any operation.

Example: Retrieving a state object

var state = mixer.getState();

console.log(state.totalShow + 'targets are currently shown');
forceRefresh()

.forceRefresh()

Type Name Description
@return void

Forces the re-indexing all targets within the container.

This should only be used if some other piece of code in your application has manipulated the contents of your container, which should be avoided.

If you need to add or remove target elements from the container, use the built-in .insert() or .remove() methods, and MixItUp will keep itself up to date.

Example: Force refreshing the mixer after external DOM manipulation

console.log(mixer.getState().totalShow); // 3

// An element is removed from the container via some external DOM manipulation code:

containerEl.removeChild(containerEl.firstElementChild);

// The mixer does not know that the number of targets has changed:

console.log(mixer.getState().totalShow); // 3

mixer.forceRefresh();

// After forceRefresh, the mixer is in sync again:

console.log(mixer.getState().totalShow); // 2
forceRender()

.forceRender()

Type Name Description
@return void

Forces the re-rendering of all targets when using the Dataset API.

By default, targets are only re-rendered when data.dirtyCheck is enabled, and an item’s data has changed when dataset() is called.

The forceRender() method allows for the re-rendering of all targets in response to some arbitrary event, such as the changing of the target render function.

Targets are rendered against their existing data.

Example: Force render targets after changing the target render function

console.log(container.innerHTML); // ... <span class="mix">Foo</span> ...

mixer.configure({
    render: {
        target: (item) => `<a href="/${item.slug}/" class="mix">${item.title}</a>`
    }
});

mixer.forceRender();

console.log(container.innerHTML); // ... <a href="/foo/" class="mix">Foo</a> ...
destroy()

.destroy([cleanUp])

Type Name Description
@param boolean [cleanUp]

An optional boolean dictating whether or not to clean up any inline display: none; styling applied to hidden targets.

@return void

Removes mixitup functionality from the container, unbinds all control event handlers, and deletes the mixer instance from MixItUp’s internal cache.

This should be performed whenever a mixer’s container is removed from the DOM, such as during a page change in a single page application, or React’s componentWillUnmount().

Example: Destroying the mixer before removing its container element

mixer.destroy();

containerEl.parentElement.removeChild(containerEl);