MixItUp 3 Migration Guide

MixItUp 3 brings some important API and functionality changes. Follow this guide for a smooth transition.

The biggest change to MixItUp with v3 is the dropping of jQuery as a dependency. MixItUp 1 and 2 both existed as jQuery plugins, with instantiation and API calls abstracted away through a typical jQuery-plugin interface.

With MixItUp 3, we can now interact with MixItUp instances (or "mixers") directly with minimal abstraction.

Instantiation

Basic Instantiation

// MixItUp 2

$('.container').mixItUp();

// MixItUp 3

var mixer = mixitup('.container');

Passing a configuration object

// MixItUp 2

$('.container').mixItUp({
    selectors: {
        target: '.item'
    }
});

// MixItUp 3

var mixer = mixitup('.container', {
    selectors: {
        target: '.item'
    }
});

MixItUp 3 adds many new configuration options, and renames or removes some of those from MixItUp 2.

Further reading: Configuration Object

Method Invocation

// MixItUp 2

$('.container').mixItUp('filter', '.category-a');

// MixItUp 3

mixer.filter('.category-a');

As you may have noticed, mixers in MixItUp 3 have many of the same API methods as were available in MixItUp 2, but are called using standard method invocation syntax, with arguments passed in the standard form rather than the jQuery-UI-like syntax of MixItUp 2.

MixItUp 3 adds many new API methods, and renames or removes some of those from MixItUp 2.

Further reading: Mixer API Methods

Promises and Callbacks

In MixItUp 2, asynchronous operations (those involving animation) accepted an optional callback function to be invoked on completion.

With MixItUp 3, all asynchronous methods return a promise resolving with a state object. Callback functions are still permitted as an optional argument, but promises should be considered the preferred method for dealing with asynchronous operations.

// MixItUp 2 (callbacks)

$('.container').mixItUp('filter', '.category-a', function(state) {
    // Operation finished, the new state is:

    console.log(state);
});

// MixItUp 3 (promises)

mixer.filter('.category-a')
    .then(function(state) {
        // Operation finished, the new state is:

        console.log(state);
    });

CSS

In MixItUp 2, it was required that a CSS display: none; rule be applied to all target elements, with MixItUp adding the display value of your choice (e.g. inline-block) to only those targets to be shown. This was intended to prevent a flash-of-content before MixItUp 2's loading animation started.

With MixItUp 3, mixers are instantiated synchronously and instantly with no loading animation. Because of this, it is assumed that all targets in the DOM are already shown, so MixItUp only needs to add display: none; to those targets to be hidden, using whatever display value is declared in your CSS for shown targets.

In short – you no longer need to set display: none; in your CSS. Simply use whatever display value your design requires, regardless of MixItUp.

Loading animations are still possible in MixItUp 3 as demonstrated in the Loading Animation demo. The code for this demo is available here.