mixitup.Config

mixitup.Config is an interface used for customising the functionality of a mixer instance. It is organised into several semantically distinct sub-objects, each one pertaining to a particular aspect of MixItUp functionality.

An object literal containing any or all of the available properies, known as the "configuration object", can be passed as the second parameter to the mixitup factory function when creating a mixer instance to customise its functionality as needed.

If no configuration object is passed, the mixer instance will take on the default configuration values detailed below.

Example 1: Creating and passing the configuration object

// Create a configuration object with desired values

var config = {
    animation: {
        enable: false
    },
    selectors: {
        target: '.item'
    }
};

// Pass the configuration object to the mixitup factory function

var mixer = mixitup(containerEl, config);

Example 2: Passing the configuration object inline

// Typically, the configuration object is passed inline for brevity.

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

mixitup.Config.animation

A group of properties defining the mixer’s animation and effects settings.

enable
Type Default
boolean true

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.

Example: Create a mixer with all animations disabled

var mixer = mixitup(containerEl, {
    animation: {
        enable: false
    }
});
effects
Type Default
string 'fade scale'

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.

Example: Apply "fade" and "translateZ" effects to all animations

// 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
Type Default
string ''

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

Example: Apply downwards vertical translate to targets being filtered in

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

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

Example: Apply upwards vertical translate to targets being filtered out

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

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

Example: Apply an animation duration of 200ms to all mixitup animations

var mixer = mixitup(containerEl, {
    animation: {
        duration: 200
    }
});
easing
Type Default
string 'ease'

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

Example 1: Apply "ease-in-out" easing to all animations

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

Example 2: Apply a custom "cubic-bezier" easing function to all animations

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

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.

Example: Prevent perspective from being applied to any 3D transforms

var mixer = mixitup(containerEl, {
    animation: {
        applyPerspective: false
    }
});
perspectiveDistance
Type Default
string '3000px'

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

Example: Set a perspective distance of 2000px

var mixer = mixitup(containerEl, {
    animation: {
        effects: 'rotateY(-25deg)',
        perspectiveDistance: '2000px'
    }
});
perspectiveOrigin
Type Default
string '50% 50%'

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

Example: Set a perspective origin in the top-right of the container

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

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.

Example: Disable queuing

var mixer = mixitup(containerEl, {
    animation: {
        queue: false
    }
});
queueLimit
Type Default
number 3

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

Example: Allow a maximum of 5 operations in the queue at any time

var mixer = mixitup(containerEl, {
    animation: {
        queueLimit: 5
    }
});
animateResizeContainer
Type Default
boolean true

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.

Example 1: Disable the transitioning of the container height and/or width

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

Example 2: Disable the transitioning of the container height and/or width for mobile devices only

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

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.

Example: Enable the transitioning of target widths and heights

var mixer = mixitup(containerEl, {
    animation: {
        animateResizeTargets: true
    }
});
staggerSequence
Type Default
function null

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.

Example 1: Stagger target elements by column in a 3-column grid

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

Example 2: Using an algorithm to produce a more complex sequence

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

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.

Example: Reverse the desired direction on any translate/rotate effect for targets being filtered out

// 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
Type Default
boolean true

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.

Example: Disable the "nudging" of targets being filtered in and out simulatenously

var mixer = mixitup(containerEl, {
    animation: {
        nudge: false
    }
});
clampHeight
Type Default
boolean true

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.

Example: Disable container height-clamping

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

mixitup.Config.callbacks

A group of optional callback functions to be invoked at various points within the lifecycle of a mixer operation.

Each function is analogous to an event of the same name triggered from the container element, and is invoked immediately after it.

All callback functions receive the current state object as their first argument, as well as other more specific arguments described below.

onMixStart
Type Default
function null

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.

Example: Adding an `onMixStart` callback function

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

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.

Example: Adding an `onMixBusy` callback function

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

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

Example: Adding an `onMixEnd` callback function

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

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

Example: Adding an `onMixFail` callback function

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

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.

Example 1: Adding an `onMixClick` callback function

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

Example 2: Using `onMixClick` to manipulate the original click event

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();
        }
    }
});

Example 3: Using `onMixClick` to conditionally cancel operations

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;
             }
        }
    }
});

mixitup.Config.controls

A group of properties relating to clickable control elements.

enable
Type Default
boolean true

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.

Example: Disabling controls

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
Type Default
boolean true

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.

Example: Setting live controls

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

// Control buttons can now be added, remove and changed without breaking
// the mixer's UI
scope
Type Default
string 'global'

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.

Example: Setting 'local' scoped controls

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
Type Default
string 'or'

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')

Example: Setting "and" toggle logic

var mixer = mixitup(containerEl, {
    controls: {
        toggleLogic: 'and'
    }
});
toggleDefault
Type Default
string 'all'

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.

Example 1: Setting the default toggle behavior to `'all'`

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
    });

Example 2: Setting the default toggle behavior to `'none'`

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
    });

mixitup.Config.classNames

A group of properties defining the output and structure of class names programmatically added to controls and containers to reflect the state of the mixer.

Most commonly, class names are added to controls by MixItUp to indicate that the control is active so that it can be styled accordingly - 'mixitup-control-active' by default.

Using a “BEM” like structure, each classname is broken into the three parts: a block namespace ('mixitup'), an element name (e.g. 'control'), and an optional modifier name (e.g. 'active') reflecting the state of the element.

By default, each part of the classname is concatenated together using single hyphens as delineators, but this can be easily customised to match the naming convention and style of your project.

block
Type Default
string 'mixitup'

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

Example 1: changing the `config.classNames.block` value

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

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

Example 2: Removing `config.classNames.block`

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

// Active control output: "control-active"
elementContainer
Type Default
string 'container'

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

elementFilter
Type Default
string 'control'

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.

Example 1: changing the `config.classNames.elementFilter` value

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

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

Example 2: changing the `config.classNames.block` and `config.classNames.elementFilter` values

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

// Active filter output: "portfolio-filter-active"
elementSort
Type Default
string 'control'

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.

Example 1: changing the `config.classNames.elementSort` value

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

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

Example 2: changing the `config.classNames.block` and `config.classNames.elementSort` values

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

// Active sort output: "portfolio-sort-active"
elementMultimix
Type Default
string 'control'

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.

Example 1: changing the `config.classNames.elementMultimix` value

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

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

Example 2: changing the `config.classNames.block` and `config.classNames.elementMultimix` values

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

// Active multimix output: "portfolio-multimix-active"
elementToggle
Type Default
string 'control'

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.

Example 1: changing the `config.classNames.elementToggle` value

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

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

Example 2: changing the `config.classNames.block` and `config.classNames.elementToggle` values

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

// Active toggle output: "portfolio-toggle-active"
modifierActive
Type Default
string 'active'

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

modifierDisabled
Type Default
string 'disabled'

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

modifierFailed
Type Default
string 'failed'

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

delineatorElement
Type Default
string '-'

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.

Example: changing the delineator to match BEM convention

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

// example active control output: "mixitup__control-active"
delineatorModifier
Type Default
string '-'

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.

Example: changing both delineators to match BEM convention

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

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

mixitup.Config.data

A group of properties relating to MixItUp’s dataset API.

uidKey
Type Default
string ''

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'.

Example: Setting the UID to `'id'`

var mixer = mixitup(containerEl, {
    data: {
        uidKey: 'id'
    }
});
dirtyCheck
Type Default
boolean false

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.

Example: Enabling dirty checking

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
   });

mixitup.Config.debug

A group of properties allowing the toggling of various debug features.

enable
Type Default
boolean false

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.

Example: Enabling debug mode

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

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

console.log(mixer);
showWarnings
Type Default
boolean true

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.

Example 1: Disabling warnings

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

Example 2: Disabling warnings based on environment

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

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

mixitup.Config.layout

A group of properties relating to the layout of the container.

allowNestedTargets
Type Default
boolean true

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.

Example: Restricting targets to immediate children

var mixer = mixitup(containerEl, {
    layout: {
        allowNestedTargets: false
    }
});
containerClassName
Type Default
string ''

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.

Example 1: Specifying a container class name

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

Example 2: Changing the default class name with `.changeLayout()`

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

mixer.changeLayout('list')
    .then(function(state) {
         console.log(state.activeContainerClass); // "list"
    });
siblingBefore
Type Default
HTMLElement null

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

Example: Setting a `siblingBefore` reference element

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

var mixer = mixitup(containerEl, {
    layout: {
        siblingBefore: addButton
    }
});
siblingAfter
Type Default
HTMLElement null

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

Example: Setting an `siblingAfter` reference element

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

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

mixitup.Config.load

A group of properties defining the initial state of the mixer on load (instantiation).

filter
Type Default
string 'all'

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'.

Example 1: Defining an initial filter selector to be applied on load

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

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

Example 2: Hiding all targets on load

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

var mixer = mixitup(containerEl, {
    load: {
        filter: 'none'
    }
});
sort
Type Default
string 'default:asc'

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';

Example: Defining sorting to be applied on load

// 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
Type Default
Array.<object> null

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.

Example: Defining the initial underyling dataset

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
    }
});

mixitup.Config.selectors

A group of properties defining the selectors used to query elements within a mixitup container.

target
Type Default
string '.mix'

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.

Example 1: Changing the target selector

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

Example 2: Using an attribute selector as a target selector

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

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

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.

Example 1: Adding a `selectors.control` selector

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

// Will not be handled:
// 

// Will be handled:
// 

mixitup.Config.render

A group of optional render functions for creating and updating elements.

All render functions receive a data object, and should return a valid HTML string.

target
Type Default
function 'null'

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.

Example 1: Using string concatenation

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

Example 2: Using an ES2015 template literal

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

Example 3: Using a Handlebars template

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

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

Example 4: Returning a DOM element

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

             var el = ...

             return el;
        }
    }
});