mixitup-3-migration-guide.md

MixItUp 3 Migration Guide

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 ('mixers') directly with minimal abstraction.

Instantiation

Example: Basic Instantiation

// MixItUp 2

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

// MixItUp 3

var mixer = mixitup('.container');

Example: Passing the configuration object

// MixItUp 2

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

// MixItUp 3

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

Note that the mixitup() factory function is now all lowercase, as apposed to the camel case MixItUp 2 jQuery method .mixItUp().

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 by default, 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, loading animations are removed by default, and mixers are instantiated synchronously and instantly. 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 layout would require, 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.