Mixitup - Documentation

Getting Started

Installation

MixItUp can be installed via npm, yarn, or by including the minified JavaScript and CSS files directly in your project.

npm:

npm install mixitup

yarn:

yarn add mixitup

CDN (for quick prototyping): Include the following <script> and <link> tags in your HTML <head>:

<link href="https://cdn.jsdelivr.net/npm/mixitup@latest/dist/mixitup.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/mixitup@latest/dist/mixitup.min.js"></script>

Remember to replace "https://cdn.jsdelivr.net/npm/mixitup@latest/dist/..." with the correct path if you are using a different CDN or local files.

Basic Usage

Once installed, MixItUp is initialized on a container element. This container should contain the items you wish to filter and sort. The basic initialization looks like this:

const mixer = mixitup(containerEl);

Where containerEl is a DOM element selector string (e.g., '#container'), or a DOM element itself. This will initialize MixItUp with its default settings. More advanced configurations are possible using options (see the full documentation for details).

Markup Requirements

Your HTML should contain a container element that holds the items you want to filter and sort. Each item within the container should have a class that can be used for filtering or sorting. For example:

<div id="container">
  <div class="mix category-1 category-2">Item 1</div>
  <div class="mix category-2 category-3">Item 2</div>
  <div class="mix category-1">Item 3</div>
</div>

Here, category-1, category-2, and category-3 are example classes used for filtering. The mix class is required for each item to be managed by MixItUp. You can add more descriptive classes as needed for styling and other purposes.

Quick Start Example

This example demonstrates a basic setup with filtering.

<!DOCTYPE html>
<html>
<head>
  <title>MixItUp Quick Start</title>
  <link href="https://cdn.jsdelivr.net/npm/mixitup@latest/dist/mixitup.min.css" rel="stylesheet">
</head>
<body>

<div id="container">
  <div class="mix category-web category-design">Web Design</div>
  <div class="mix category-web category-development">Web Development</div>
  <div class="mix category-design">Graphic Design</div>
</div>

<button data-filter=".category-web">Web</button>
<button data-filter=".category-design">Design</button>
<button data-filter="all">All</button>

<script src="https://cdn.jsdelivr.net/npm/mixitup@latest/dist/mixitup.min.js"></script>
<script>
  const mixer = mixitup('#container');
</script>

</body>
</html>

Remember to replace the CDN links with your local paths if you installed MixItUp locally. This example shows how to filter elements by clicking the buttons; the data-filter attribute on each button tells MixItUp which elements to show. The all filter shows all elements. Further interaction functionalities like sorting will require additional configuration which is explained further in the advanced usage section of the documentation.

Core Functionality

Filtering

MixItUp’s filtering functionality allows you to display only the items that match specific criteria. Filtering is achieved using selectors that target classes or attributes on your items.

Basic Filtering:

Filtering is triggered using the filter() method:

mixer.filter('.category-a'); // Shows only items with class 'category-a'
mixer.filter('all'); // Shows all items
mixer.filter('none'); // Hides all items
mixer.filter('.category-a, .category-b'); // Shows items with class 'category-a' or 'category-b'

You can also filter using more complex selectors, including those with negation (\:not()), attribute selectors ([attribute="value"]), and more.

Filtering with Multiple Selectors:

Combine selectors to filter based on multiple criteria. For instance, to show only items that have both category-a and category-b classes, you need to use the filter method appropriately. While .category-a.category-b might seem logical, using an intersection of selectors is recommended for complex scenarios to prevent ambiguity:

mixer.filter(function(item) {
  return item.classList.contains('category-a') && item.classList.contains('category-b');
});

Dynamic Filtering:

You can dynamically filter your items by passing a selector string to the filter() method. This is useful when you want to react to user interactions, such as selecting options in a dropdown menu. For example, update the filter based on a dropdown selection:

const select = document.getElementById('filter-select');
select.addEventListener('change', function() {
  mixer.filter(this.value);
});

Sorting

MixItUp allows sorting items based on different criteria. You specify the sorting criteria using the sort() method.

Basic Sorting:

mixer.sort('default'); // Resets to the default order
mixer.sort('name:asc'); // Sorts by the 'name' attribute in ascending order
mixer.sort('name:desc'); // Sorts by the 'name' attribute in descending order

The attribute used for sorting must be available in your items (either as a data attribute or a class).

Sorting with Multiple Criteria:

Sort by multiple criteria by passing an array of sort strings:

mixer.sort([
  'name:asc',
  'date:desc'
]); // Sorts by name ascending, then by date descending

Custom Sorting:

For more complex sorting scenarios, you can provide a custom sorting function:

mixer.sort(function(a, b) {
    //Custom comparison function for comparing 'a' and 'b'
    return a.dataset.value - b.dataset.value; //Example numerical sorting
});

Pagination

MixItUp doesn’t directly handle pagination, but you can easily implement it by combining its filtering and sorting capabilities with some simple DOM manipulation. You’ll need to manage the display of items yourself, showing only the items for the current page. For instance, you might show 10 items per page and use buttons to navigate through them.

Multi-Mix

MixItUp can be used to manage multiple instances on a single page. Simply initialize MixItUp on different container elements separately:

const mixer1 = mixitup('#container1');
const mixer2 = mixitup('#container2');

Each mixer instance is independent and you can control them individually. Events fired by one instance are not passed to others.

Events

MixItUp provides a rich set of events that you can listen for to respond to changes in the layout. Events are triggered at different stages of the filter and sort operations, allowing you to update the UI or perform other actions based on the current state of the mix. Some of the most common events include:

Attach event listeners using the on() method:

mixer.on('mixEnd', function(state) {
  console.log('Mix complete!', state); // 'state' object contains information about the current state
});

You can also use off() to remove event listeners and once() to trigger an event listener only once. Refer to the complete API documentation for a full list of available events and their properties.

Configuration Options

MixItUp offers a wide range of configuration options to customize its behavior and appearance. These options are passed as an object to the mixitup() constructor.

Selectors

Selectors define which elements MixItUp should manage and which elements act as controls for filtering and sorting.

Controls

Controls configure how MixItUp interacts with filter and sort buttons. This section describes attributes commonly used within those controls.

Layout

Layout options affect the arrangement of items within the container.

Animation

Animation options control the visual effects of filtering and sorting.

Testing and Debugging

Advanced Techniques

Custom Animations

While MixItUp provides several built-in animation effects, you can create fully custom animations using CSS transitions or JavaScript animations. For CSS transitions, define your animation styles and use the transition configuration option. For more complex animations, you can use JavaScript animation libraries in conjunction with MixItUp’s events.

CSS Transitions: Define the animation in your CSS and set the transition option in MixItUp’s configuration:

.mix {
  transition: transform 0.5s ease, opacity 0.5s ease; /* Define transition properties */
}

.mix.mix-show {
  transform: scale(1);
  opacity: 1;
}

.mix.mix-hide {
  transform: scale(0.5);
  opacity: 0;
}
const mixer = mixitup({
    container: '#container',
    transition: 'transform 0.5s ease, opacity 0.5s ease' // Using CSS transitions
});

JavaScript Animations: Use MixItUp’s events (mixStart, mixEnd) to trigger your custom JavaScript animations.

Data Attributes

Data attributes are extremely useful for managing data associated with each item, especially when working with complex filtering or sorting. You can store any kind of information within data attributes. For example, you could store the name, price, and category of a product in data attributes, then filter and sort based on this data:

<div class="mix" data-name="Product A" data-price="19.99" data-category="electronics">...</div>
<div class="mix" data-name="Product B" data-price="29.99" data-category="clothing">...</div>

You would then access these attributes within your filtering and sorting functions, or use them in the data-sort attribute of your controls to sort:

mixer.sort('data-price:asc');  //Sort by price ascending

Working with AJAX

MixItUp can seamlessly integrate with AJAX to load and update content dynamically. Use AJAX to fetch data from a server, then update the container with the new content. You’ll need to re-initialize MixItUp after updating the container’s contents to manage the newly added items. For instance:

$.ajax({
  url: '/products.json',
  success: function(data) {
    // Update the container with the new data
    $('#container').html(data);

    // Re-initialize MixItUp
    mixer = mixitup('#container');
  }
});

Integration with Other Libraries

MixItUp can be combined with other JavaScript libraries, such as those for UI components (dropdowns, modals), image loading, and more. Ensure proper initialization order to avoid conflicts. For example, initialize MixItUp after any library that modifies the DOM.

Performance Optimization

For large datasets, optimize performance by:

API Reference

This section details the core API methods available for interacting with a MixItUp instance. Remember to replace mixer with your MixItUp instance variable. All methods, unless otherwise specified, return the instance of mixer for method chaining. Refer to the complete documentation for detailed explanations of parameters and return values.

mixitup()

Initializes a new MixItUp instance.

const mixer = mixitup(target, options);

filter()

Filters the items based on a selector.

mixer.filter(selector, animate, callback);

sort()

Sorts the items based on the given criteria.

mixer.sort(sortString, animate, callback);

toggleFilter()

Toggles the filter state of a given selector string.

mixer.toggleFilter(selector, animate, callback);

show()

Shows the items matching the given selector.

mixer.show(selector, animate, callback);

hide()

Hides the items matching the given selector.

mixer.hide(selector, animate, callback);

insertBefore()

Inserts the given element(s) before the target element.

mixer.insertBefore(element, targetElement);

insertAfter()

Inserts the given element(s) after the target element.

mixer.insertAfter(element, targetElement);

append()

Appends the given element(s) to the container.

mixer.append(element);

prepend()

Prepends the given element(s) to the container.

mixer.prepend(element);

remove()

Removes the given element(s) from the container.

mixer.remove(element, animate, callback);

destroy()

Destroys the MixItUp instance, removing event listeners and resetting the container.

mixer.destroy();

isMixing()

Returns a boolean indicating whether a mix animation is currently in progress.

const isMixing = mixer.isMixing();

getState()

Returns an object representing the current state of the mixer.

const state = mixer.getState();

getContainer()

Returns the container element.

const container = mixer.getContainer();

getTarget()

Returns the target element(s).

const target = mixer.getTarget();

resetFilters()

Resets all filters to their default state.

mixer.resetFilters(animate, callback);

resetSort()

Resets the sort order to its default state.

mixer.resetSort(animate, callback);

forceRefresh()

Forces MixItUp to re-calculate the layout and positions of its items. Useful after significant DOM manipulations outside of MixItUp’s control.

mixer.forceRefresh();

Troubleshooting

This section covers common issues encountered when using MixItUp, debugging techniques, and known limitations.

Common Issues

Debugging Tips

Known Limitations