Configuration Object

enable

A boolean dictating whether or not animation should be enabled for the MixItUp instance. If false, all operations will occur instantly and syncronously, although callback functions and any returned promises will still be fulfilled.

var mixer = mixitup(containerEl, {
    animation: {
        enable: false
    }
});

effects

A string of one or more space-seperated properties to which transitions will be applied for all filtering animations.

Properties can be listed any order or combination, although they will be applied in a specific predefined order to produce consistent results.

To learn more about available effects, experiment with our sandbox demo and try out the “Export config” button in the Animation options drop down.

// As targets are filtered in and out, they will fade between
// opacity 1 and 0 and transform between translateZ(-100px) and
// translateZ(0).

var mixer = mixitup(containerEl, {
    animation: {
        effects: 'fade translateZ(-100px)'
    }
});

effectsIn

A string of one or more space-seperated effects to be applied only to filter-in animations, overriding config.animation.effects if set.

var mixer = mixitup(containerEl, {
    animation: {
        effectsIn: 'fade translateY(-100%)'
    }
});

effectsOut

A string of one or more space-seperated effects to be applied only to filter-out animations, overriding config.animation.effects if set.

var mixer = mixitup(containerEl, {
    animation: {
        effectsOut: 'fade translateY(-100%)'
    }
});

duration

An integer dictating the duration of all MixItUp animations in milliseconds, not including any additional delay apllied via the 'stagger' effect.

var mixer = mixitup(containerEl, {
    animation: {
        duration: 200
    }
});

easing

A valid CSS3 transition-timing function or shorthand. For a full list of accepted values, visit easings.net.

var mixer = mixitup(containerEl, {
    animation: {
        easing: 'ease-in-out'
    }
});

var mixer = mixitup(containerEl, {
    animation: {
        easing: 'cubic-bezier(0.645, 0.045, 0.355, 1)'
    }
});

applyPerspective

A boolean dictating whether or not to apply perspective to the MixItUp container during animations. By default, perspective is always applied and creates the illusion of three-dimensional space for effects such as translateZ, rotateX, and rotateY.

You may wish to disable this and define your own perspective settings via CSS.

var mixer = mixitup(containerEl, {
    animation: {
        applyPerspective: false
    }
});

perspectiveDistance

The perspective distance value to be applied to the container during animations, affecting any 3D-transform-based effects.

var mixer = mixitup(containerEl, {
    animation: {
        effects: 'rotateY(-25deg)',
        perspectiveDistance: '2000px'
    }
});

perspectiveOrigin

The perspective-origin value to be applied to the container during animations, affecting any 3D-transform-based effects.

var mixer = mixitup(containerEl, {
    animation: {
        effects: 'transateZ(-200px)',
        perspectiveOrigin: '100% 0'
    }
});

queue

A boolean dictating whether or not to enable the queuing of operations.

If true (default), and a control is clicked or an API call is made while another operation is progress, the operation will go into the queue and will be automatically exectuted when the previous operaitons is finished.

If false, any requested operations will be ignored, and the onMixBusy callback and mixBusy event will be fired. If debug.showWarnings is enabled, a console warning will also occur.

var mixer = mixitup(containerEl, {
    animation: {
        queue: false
    }
});

queueLimit

An integer dictacting the maximum number of operations allowed in the queue at any time, when queuing is enabled.

var mixer = mixitup(containerEl, {
    animation: {
        queueLimit: 5
    }
});

animateResizeContainer

A boolean dictating whether or not to transition the height and width of the container as elements are filtered in and out. If disabled, the container height will change abruptly.

It may be desirable to disable this on mobile devices as the CSS height and width properties do not receive GPU-acceleration and can therefore cause stuttering.

var mixer = mixitup(containerEl, {
    animation: {
        animateResizeContainer: false
    }
});

var mixer = mixitup(containerEl, {
    animation: {
        animateResizeContainer: myFeatureTests.isMobile ? false : true
    }
});

animateResizeTargets

A boolean dictating whether or not to transition the height and width of target elements as they change throughout the course of an animation.

This is often a must for flex-box grid layouts where the size of target elements may change depending on final their position in relation to their siblings, or for .changeLayout() operations where the size of targets change between layouts.

NB: This feature requires additional calculations and manipulation to non-hardware-accelerated properties which may adversely affect performance on slower devices, and is therefore disabled by default.

var mixer = mixitup(containerEl, {
    animation: {
        animateResizeTargets: true
    }
});

staggerSequence

A custom function used to manipulate the order in which the stagger delay is incremented when using the ‘stagger’ effect.

When using the ‘stagger’ effect, the delay applied to each target element is incremented based on its index. You may create a custom function to manipulate the order in which the delay is incremented and create engaging non-linear stagger effects.

The function receives the index of the target element as a parameter, and must return an integer which serves as the multiplier for the stagger delay.

var mixer = mixitup(containerEl, {
    animation: {
        effects: 'fade stagger(100ms)',
        staggerSequence: function(i) {
            return i % 3;
        }
    }
});

var mixer = mixitup(containerEl, {
    animation: {
        effects: 'fade stagger(100ms)',
        staggerSequence: function(i) {
            return (2*i) - (5*((i/3) - ((1/3) * (i%3))));
        }
    }
});

reverseOut

A boolean dictating whether or not to reverse the direction of translate and rotate transforms for elements being filtered out.

It can be used to create carousel-like animations where elements enter and exit from opposite directions. If enabled, the effect translateX(-100%) for elements being filtered in would become translateX(100%) for targets being filtered out.

This functionality can also be achieved by providing seperate effects strings for config.animation.effectsIn and config.animation.effectsOut.

// Elements being filtered in will be translated from '100%' to '0' while
// elements being filtered out will be translated from 0 to '-100%'

var mixer = mixitup(containerEl, {
    animation: {
        effects: 'fade translateX(100%)',
        reverseOut: true,
        nudge: false // Disable nudging to create a carousel-like effect
    }
});

nudge

A boolean dictating whether or not to “nudge” the animation path of targets when they are being filtered in and out simulatenously.

This has been the default behavior of MixItUp since version 1, but it may be desirable to disable this effect when filtering directly from one exclusive set of targets to a different exclusive set of targets, to create a carousel-like effect, or a generally more subtle animation.

var mixer = mixitup(containerEl, {
    animation: {
        nudge: false
    }
});

clampHeight

A boolean dictating whether or not to clamp the height of the container while MixItUp’s geometry tests are carried out before an operation.

To prevent scroll-bar flicker, clamping is turned on by default. But in the case where the height of the container might affect its vertical positioning in the viewport (e.g. a vertically-centered container), this should be turned off to ensure accurate test results and a smooth animation.

var mixer = mixitup(containerEl, {
    animation: {
        clampHeight: false
    }
});

clampWidth

A boolean dictating whether or not to clamp the width of the container while MixItUp’s geometry tests are carried out before an operation.

To prevent scroll-bar flicker, clamping is turned on by default. But in the case where the width of the container might affect its horitzontal positioning in the viewport (e.g. a horizontall-centered container), this should be turned off to ensure accurate test results and a smooth animation.

var mixer = mixitup(containerEl, {
    animation: {
        clampWidth: false
    }
});

liveSort

A boolean dictating whether to allow “live” sorting of the mixer.

Because of the expensive nature of sorting, MixItUp makes use of several internal optimizations to skip redundant sorting operations, such as when the newly requested sort command is the same as the active one. The caveat to this optimization is that “live” edits to the value of a target’s sorting attribute will be ignored when requesting a re-sort by the same attribute.

By setting to behavior.liveSort to true, the mixer will always re-sort regardless of whether or not the sorting attribute and order have changed.

var mixer = mixitup(containerEl, {
    behavior: {
        liveSort: true
    },
    load: {
        sort: 'edited:desc'
    }
});

var target = containerEl.children[3];

console.log(target.getAttribute('data-edited')); // '2015-04-24'

target.setAttribute('data-edited', '2017-08-10'); // Update the target's edited date

mixer.sort('edited:desc')
    .then(function(state) {
        // The target is now at the top of the list

        console.log(state.targets[0] === target); // true
    });

onMixStart

A callback function invoked immediately after any MixItUp operation is requested and before animations have begun.

A second futureState argument is passed to the function which represents the final state of the mixer once the requested operation has completed.

var mixer = mixitup(containerEl, {
    callbacks: {
        onMixStart: function(state, futureState) {
             console.log('Starting operation...');
        }
    }
});

onMixBusy

A callback function invoked when a MixItUp operation is requested while another operation is in progress, and the animation queue is full, or queueing is disabled.

var mixer = mixitup(containerEl, {
    callbacks: {
        onMixBusy: function(state) {
             console.log('Mixer busy');
        }
    }
});

onMixEnd

A callback function invoked after any MixItUp operation has completed, and the state has been updated.

var mixer = mixitup(containerEl, {
    callbacks: {
        onMixEnd: function(state) {
             console.log('Operation complete');
        }
    }
});

onMixFail

A callback function invoked whenever an operation "fails", i.e. no targets could be found matching the requested filter.

var mixer = mixitup(containerEl, {
    callbacks: {
        onMixFail: function(state) {
             console.log('No items could be found matching the requested filter');
        }
    }
});

onMixClick

A callback function invoked whenever a MixItUp control is clicked, and before its respective operation is requested.

The clicked element is assigned to the this keyword within the function. The original click event is passed to the function as the second argument, which can be useful if using <a> tags as controls where the default behavior needs to be prevented.

Returning false from the callback will prevent the control click from triggering an operation.

var mixer = mixitup(containerEl, {
    callbacks: {
        onMixClick: function(state, originalEvent) {
             console.log('The control "' + this.innerText + '" was clicked');
        }
    }
});

var mixer = mixitup(containerEl, {
    callbacks: {
        onMixClick: function(state, originalEvent) {
             // Prevent original click event from bubbling up:
             originalEvent.stopPropagation();

             // Prevent default behavior of clicked element:
             originalEvent.preventDefault();
        }
    }
});

var mixer = mixitup(containerEl, {
    callbacks: {
        onMixClick: function(state, originalEvent) {
             // Perform some conditional check:

             if (myApp.isLoading) {
                 // By returning false, we can prevent the control click from triggering an operation.

                 return false;
             }
        }
    }
});

enable

A boolean dictating whether or not controls should be enabled for the mixer instance.

If true (default behavior), MixItUp will search the DOM for any clickable elements with data-filter, data-sort or data-toggle attributes, and bind them for click events.

If false, no click handlers will be bound, and all functionality must therefore be performed via the mixer’s API methods.

If you do not intend to use the default controls, setting this property to false will marginally improve the startup time of your mixer instance, and will also prevent any other active mixer instances in the DOM which are bound to controls from controlling the instance.

var mixer = mixitup(containerEl, {
    controls: {
        enable: false
    }
});

// With the default controls disabled, we can only control
// the mixer via its API methods, e.g.:

mixer.filter('.cat-1');

live

A boolean dictating whether or not to use event delegation when binding click events to the default controls.

If false (default behavior), each control button in the DOM will be found and individually bound when a mixer is instantiated, with their corresponding actions cached for performance.

If true, a single click handler will be applied to the window (or container element - see config.controls.scope), and any click events triggered by elements with data-filter, data-sort or data-toggle attributes present will be handled as they propagate upwards.

If you require a user interface where control buttons may be added, removed, or changed during the lifetime of a mixer, controls.live should be set to true. There is a marginal but unavoidable performance deficit when using live controls, as the value of each control button must be read from the DOM in real time once the click event has propagated.

var mixer = mixitup(containerEl, {
    controls: {
        live: true
    }
});

// Control buttons can now be added, remove and changed without breaking
// the mixer's UI

scope

A string dictating the “scope” to use when binding or querying the default controls. The available values are 'global' or 'local'.

When set to 'global' (default behavior), MixItUp will query the entire document for control buttons to bind, or delegate click events from (see config.controls.live).

When set to 'local', MixItUp will only query (or bind click events to) its own container element. This may be desireable if you require multiple active mixer instances within the same document, with controls that would otherwise intefere with each other if scoped globally.

Conversely, if you wish to control multiple instances with a single UI, you would create one set of controls and keep the controls scope of each mixer set to global.

var mixerOne = mixitup(containerOne, {
    controls: {
        scope: 'local'
    }
});

var mixerTwo = mixitup(containerTwo, {
    controls: {
        scope: 'local'
    }
});

// Both mixers can now exist within the same document with
// isolated controls placed within their container elements.

toggleLogic

A string dictating the type of logic to apply when concatenating the filter selectors of active toggle buttons (i.e. any clickable element with a data-toggle attribute).

If set to 'or' (default behavior), selectors will be concatenated together as a comma-seperated list. For example:

'.cat-1, .cat-2' (shows any elements matching '.cat-1' OR '.cat-2')

If set to 'and', selectors will be directly concatenated together. For example:

'.cat-1.cat-2' (shows any elements which match both '.cat-1' AND '.cat-2')

var mixer = mixitup(containerEl, {
    controls: {
        toggleLogic: 'and'
    }
});

toggleDefault

A string dictating the filter behavior when all toggles are inactive.

When set to 'all' (default behavior), all targets will be shown by default when no toggles are active, or at the moment all active toggles are toggled off.

When set to 'none', no targets will be shown by default when no toggles are active, or at the moment all active toggles are toggled off.

var mixer = mixitup(containerEl, {
    controls: {
        toggleDefault: 'all'
    }
});

mixer.toggleOn('.cat-2')
    .then(function() {
        // Deactivate all active toggles

        return mixer.toggleOff('.cat-2')
    })
    .then(function(state) {
         console.log(state.activeFilter.selector); // 'all'
         console.log(state.totalShow); // 12
    });

var mixer = mixitup(containerEl, {
    controls: {
        toggleDefault: 'none'
    }
});

mixer.toggleOn('.cat-2')
    .then(function() {
        // Deactivate all active toggles

        return mixer.toggleOff('.cat-2')
    })
    .then(function(state) {
         console.log(state.activeFilter.selector); // 'none'
         console.log(state.totalShow); // 0
    });

block

The “block” portion, or top-level namespace added to the start of any class names created by MixItUp.

var mixer = mixitup(containerEl, {
    classNames: {
        block: 'portfolio'
    }
});

// Active control output: "portfolio-control-active"

var mixer = mixitup(containerEl, {
    classNames: {
        block: ''
    }
});

// Active control output: "control-active"

elementContainer

The “element” portion of the class name added to container.

elementFilter

The “element” portion of the class name added to filter controls.

By default, all filter, sort, multimix and toggle controls take the same element value of 'control', but each type’s element value can be individually overwritten to match the unique classNames of your controls as needed.

var mixer = mixitup(containerEl, {
    classNames: {
        elementFilter: 'filter'
    }
});

// Active filter output: "mixitup-filter-active"

var mixer = mixitup(containerEl, {
    classNames: {
        block: 'portfolio',
        elementFilter: 'filter'
    }
});

// Active filter output: "portfolio-filter-active"

elementSort

The “element” portion of the class name added to sort controls.

By default, all filter, sort, multimix and toggle controls take the same element value of 'control', but each type’s element value can be individually overwritten to match the unique classNames of your controls as needed.

var mixer = mixitup(containerEl, {
    classNames: {
        elementSort: 'sort'
    }
});

// Active sort output: "mixitup-sort-active"

var mixer = mixitup(containerEl, {
    classNames: {
        block: 'portfolio',
        elementSort: 'sort'
    }
});

// Active sort output: "portfolio-sort-active"

elementMultimix

The “element” portion of the class name added to multimix controls.

By default, all filter, sort, multimix and toggle controls take the same element value of 'control', but each type’s element value can be individually overwritten to match the unique classNames of your controls as needed.

var mixer = mixitup(containerEl, {
    classNames: {
        elementMultimix: 'multimix'
    }
});

// Active multimix output: "mixitup-multimix-active"

var mixer = mixitup(containerEl, {
    classNames: {
        block: 'portfolio',
        elementSort: 'multimix'
    }
});

// Active multimix output: "portfolio-multimix-active"

elementToggle

The “element” portion of the class name added to toggle controls.

By default, all filter, sort, multimix and toggle controls take the same element value of 'control', but each type’s element value can be individually overwritten to match the unique classNames of your controls as needed.

var mixer = mixitup(containerEl, {
    classNames: {
        elementToggle: 'toggle'
    }
});

// Active toggle output: "mixitup-toggle-active"

var mixer = mixitup(containerEl, {
    classNames: {
        block: 'portfolio',
        elementToggle: 'toggle'
    }
});

// Active toggle output: "portfolio-toggle-active"

modifierActive

The “modifier” portion of the class name added to active controls.

modifierDisabled

The “modifier” portion of the class name added to disabled controls.

modifierFailed

The “modifier” portion of the class name added to the container when in a “failed” state.

delineatorElement

The delineator used between the “block” and “element” portions of any class name added by MixItUp.

If the block portion is ommited by setting it to an empty string, no delineator will be added.

var mixer = mixitup(containerEl, {
    classNames: {
        delineatorElement: '__'
    }
});

// example active control output: "mixitup__control-active"

delineatorModifier

The delineator used between the “element” and “modifier” portions of any class name added by MixItUp.

If the element portion is ommited by setting it to an empty string, no delineator will be added.

var mixer = mixitup(containerEl, {
    classNames: {
        delineatorElement: '__'
        delineatorModifier: '--'
    }
});

// Active control output: "mixitup__control--active"

uidKey

A string specifying the name of the key containing your data model’s unique identifier (UID). To use the dataset API, a UID key must be specified and be present and unique on all objects in the dataset you provide to MixItUp.

For example, if your dataset is made up of MongoDB documents, the UID key would be 'id' or '_id'.

var mixer = mixitup(containerEl, {
    data: {
        uidKey: 'id'
    }
});

dirtyCheck

A boolean dictating whether or not MixItUp should “dirty check” each object in your dataset for changes whenever .dataset() is called, and re-render any targets for which a change is found.

Depending on the complexity of your data model, dirty checking can be expensive and is therefore disabled by default.

NB: For changes to be detected, a new immutable instance of the edited model must be provided to mixitup, rather than manipulating properties on the existing instance. If your changes are a result of a DB write and read, you will most likely be calling .dataset() with a clean set of objects each time, so this will not be an issue.

var myDataset = [
    {
        id: 0,
        title: "Blog Post Title 0"
        ...
    },
    {
        id: 1,
        title: "Blog Post Title 1"
        ...
    }
];

// Instantiate a mixer with a pre-loaded dataset, and a target renderer
// function defined

var mixer = mixitup(containerEl, {
    data: {
        uidKey: 'id',
        dirtyCheck: true
    },
    load: {
        dataset: myDataset
    },
    render: {
        target: function() { ... }
    }
});

// For illustration, we will clone and edit the second object in the dataset.
// NB: this would typically be done server-side in response to a DB update,
and then re-queried via an API.

myDataset[1] = Object.assign({}, myDataset[1]);

myDataset[1].title = 'Blog Post Title 11';

mixer.dataset(myDataset)
   .then(function() {
       // the target with ID "1", will be re-rendered reflecting its new title
   });

enable

A boolean dictating whether or not the mixer instance returned by the mixitup() factory function should expose private properties and methods.

By default, mixer instances only expose their public API, but enabling debug mode will give you access to various mixer internals which may aid in debugging, or the authoring of extensions.

var mixer = mixitup(containerEl, {
    debug: {
        enable: true
    }
});

// Private properties and methods will now be visible on the mixer instance:

console.log(mixer);

showWarnings

A boolean dictating whether or not warnings should be shown when various common gotchas occur.

Warnings are intended to provide insights during development when something occurs that is not a fatal, but may indicate an issue with your integration, and are therefore turned on by default. However, you may wish to disable them in production.

var mixer = mixitup(containerEl, {
    debug: {
        showWarnings: false
    }
});

var showWarnings = myAppConfig.environment === 'development' ? true : false;

var mixer = mixitup(containerEl, {
    debug: {
        showWarnings: showWarnings
    }
});

allowNestedTargets

A boolean dictating whether or not mixitup should query all descendants of the container for targets, or only immediate children.

By default, mixitup will query all descendants matching the selectors.target selector when indexing targets upon instantiation. This allows for targets to be nested inside a sub-container which is useful when ring-fencing targets from locally scoped controls in your markup (see controls.scope).

However, if you are building a more complex UI requiring the nesting of mixers within mixers, you will most likely want to limit targets to immediate children of the container by setting this property to false.

var mixer = mixitup(containerEl, {
    layout: {
        allowNestedTargets: false
    }
});

containerClassName

A string specifying an optional class name to apply to the container when in its default state.

By changing this class name or adding a class name to the container via the .changeLayout() API method, the CSS layout of the container can be changed, and MixItUp will attemp to gracefully animate the container and its targets between states.

var mixer = mixitup(containerEl, {
    layout: {
        containerClassName: 'grid'
    }
});

var mixer = mixitup(containerEl, {
    layout: {
        containerClassName: 'grid'
    }
});

mixer.changeLayout('list')
    .then(function(state) {
         console.log(state.activeContainerClass); // "list"
    });

siblingBefore

A reference to a non-target sibling element after which to insert targets when there are no targets in the container.

var addButton = containerEl.querySelector('button');

var mixer = mixitup(containerEl, {
    layout: {
        siblingBefore: addButton
    }
});

siblingAfter

A reference to a non-target sibling element before which to insert targets when there are no targets in the container.

var gap = containerEl.querySelector('.gap');

var mixer = mixitup(containerEl, {
    layout: {
        siblingAfter: gap
    }
});

filter

A string defining any filtering to be statically applied to the mixer on load. As per the .filter() API, this can be any valid selector string, or the values 'all' or 'none'.

// The mixer will show only those targets matching '.category-a' on load.

var mixer = mixitup(containerEl, {
    load: {
        filter: '.category-a'
    }
});

// The mixer will show hide all targets on load.

var mixer = mixitup(containerEl, {
    load: {
        filter: 'none'
    }
});

sort

A string defining any sorting to be statically applied to the mixer on load. As per the .sort() API, this should be a valid “sort string” made up of an attribute to sort by (or 'default') followed by an optional sorting order, or the value 'random';

// The mixer will sort the container by the value of the `data-published-date`
// attribute, in descending order.

var mixer = mixitup(containerEl, {
    load: {
        sort: 'published-date:desc'
    }
});

dataset

An array of objects representing the underlying data of any pre-rendered targets, when using the .dataset() API.

NB: If targets are pre-rendered when the mixer is instantiated, this must be set.

var myDataset = [
    {
        id: 0,
        title: "Blog Post Title 0",
        ...
    },
    {
        id: 1,
        title: "Blog Post Title 1",
        ...
    }
];

var mixer = mixitup(containerEl, {
    data: {
        uidKey: 'id'
    },
    load: {
        dataset: myDataset
    }
});

target

A selector string used to query and index target elements within the container.

By default, the class selector '.mix' is used, but this can be changed to an attribute or element selector to match the style of your project.

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

// The mixer will search for any children with the attribute `data-ref="mix"`

var mixer = mixitup(containerEl, {
    selectors: {
        target: '[data-ref="mix"]'
    }
});

control

A optional selector string used to add further specificity to the querying of control elements, in addition to their mandatory data attribute (e.g. data-filter, data-toggle, data-sort).

This can be used if other elements in your document must contain the above attributes (e.g. for use in third-party scripts), and would otherwise interfere with MixItUp. Adding an additional control selector of your choice allows MixItUp to restrict event handling to only those elements matching the defined selector.

var mixer = mixitup(containerEl, {
    selectors: {
        control: '.mixitup-control'
    }
});

// Will not be handled:
// 

// Will be handled:
// 

target

A function returning an HTML string representing a target element, or a reference to a single DOM element.

The function is invoked as part of the .dataset() API, whenever a new item is added to the dataset, or an item in the dataset changes (if dataset.dirtyCheck is enabled).

The function receives the relevant dataset item as its first parameter.

var mixer = mixitup(containerEl, {
    render: {
        target: function(item) {
            return (
                '<div class="mix">' +
                    '<h2>' + item.title + '</h2>' +
                '</div>'
            );
        }
    }
});

var mixer = mixitup(containerEl, {
    render: {
        target: function(item) {
            return (
                `<div class="mix">
                    <h2>${item.title}</h2>
                 </div>`
            );
        }
    }
});

var targetTemplate = Handlebars.compile('<div class="mix"><h2>{{title}}</h2></div>');

var mixer = mixitup(containerEl, {
    render: {
        target: targetTemplate
    }
});

var mixer = mixitup(containerEl, {
    render: {
        target: function(item) {
             // Create a single element using your framework's built-in renderer

             var el = ...

             return el;
        }
    }
});