Premium extensions are downloaded from your KunkaLabs account after purchase and are not publicly available via GitHub or NPM. Once downloaded they can be included in your project in a directory of your choosing, and then required as modules, or globally via a script tag.
Alternatively, premium extensions can also be hosted in your organization's private NPM or Github account. You may then run
npm install using that repository's path.
If using a script tag, you simply need to load the multifilter distribution script (i.e.
mixitup-multifilter.min.js) after mixitup, and the extension will automatically detect the
mixitup global variable and install itself.
mixitup.use() with the extension passed in as an argument. Your extension will be installed and made available to all MixItUp instances throughout your project.
You need only call the
.use() function once per project, per extension, as module loaders will cache a single reference to MixItUp inclusive of all changes made.
MixItUp MultiFilter extends MixItUp's API and configuration object with various new methods and properties, and adds the ability to query and index groups of filter controls, known as "filter groups".
By default, multifilter functionality is disabled so that you can use MixItUp as normal, even with the extension installed. To enable multifilter functionality for a mixer, you simply need set the
multifilter.enable configuration option to
MixItUp MultiFilter is designed to be used with content requiring filtering by multiple distinct attributes or "dimensions". Taking a clothing store as an example, some dimensions might include type (e.g. sweaters, shirts, jackets), color (red, green, blue), and size (small, medium, large).
Another example is our sandbox demo which uses the dimensions of shape (e.g. square, triangle, circle), color, and size.
MixItUp MultiFilter allows us to combine filter selectors within each of these dimensions, using a variety of logic. To learn more about MixItUp filter logic, you may wish to read the Filtering with MixItUp tutorial before continuing.
Filter Group UI
Filter groups are an essential part of a multifilter-enabled mixer and are defined in your markup. Each group represents a particular dimension, and can contain a many different types of UI within it. Filter groups are queried by MixItUp based on the presence of a
data-filter-group attribute. You may use any outer element as a filter group, but
<fieldset> makes sense semantically, particularly when using inputs like checkboxes or radios within it.
You can think of your entire multifilter UI as a
<form> with which to interact with your mixer.
Wrapping filter groups in a parent <form> is optional, but provides the ability to use submit and reset buttons as part of your UI.
In the example above, filter control buttons are used in the first group, and toggle control buttons are used in the second group. To recap the Filtering with MixItUp tutorial, filter controls allow one active control at a time, and toggle controls allow multiple active controls simultaneously. This behavior is also true when using filter groups, but is confined to within the group. Therefore, the UI above would allow us to select one type of clothing, but multiple colors.
Filter and toggle controls are just two example of the different types of UI available in MixItUp MultiFilter. Let's take a look at what else is available:
Providing the same functionality as MixItUp's filter controls (one active input at a time), radios provide a more form-like UI with a smaller footprint.
Providing the same functionality as MixItUp's toggle controls (multiple active inputs at a time), checkboxes also provide a more form-like UI with a smaller footprint.
Selects can be used to select one value from many values with a very small footprint. If the multiple attribute is added (
<select multiple>), selects can also be used to select multiple values.
Text inputs can be used to search targets by a partial or complete string. A
data-search-attribute must be added to the input to tell MixItUp which attribute to search. The example above searches the
class attribute, consistent with the other examples. For example, entering the string
'Gree' would show any targets with the class
The value of your text input will be converted to lowercase before searching, so ensure that the contents of the attribute you intend to search are also lowercase.
Configuring Filter Group Logic
MixItUp MultiFilter allows us to define one type of logic between filter groups and another type within them, using the configuration options
The most common (and default) combination of logic is
'or' within groups and
'and' between. It should be noted that this combination will suit the vast majority of multifiltering projects, but you may configure either of these properties to be
'or' as necessary.
You may also override the
multifilter.logicWithin setting on a per-group basis by adding a
data-logic attribute to your filter group's markup, with a value of either
To visualize what's meant by combining logic between groups, consider the following:
Show (shirts OR sweaters) AND (red OR blue) AND large
This would be an example or
'or' logic within groups, and
'and' logic between, and as noted above, is the most common combination of logic. Given this combination of active UI elements, MixItUp MultiFilter will generate the following selector string with which to filter the content of your container:
To help with debugging and development you may wish to console log the generated selector using one of MixItUp's callback functions. For example:
In addition to the configuration options already mentioned, MixItUp MultiFilter also makes use of several existing configuration options from the MixItUp core. These include:
Defines the toggle filter state when all controls are deactivated. The available options are
'all' (default), or
Defines whether multifilter UI should be isolated to a specific mixer (
'local'), or global to the document (
See the Configuration Object documentation page for more information about configuring MixItUp MultiFilter.
Additional Form Behavior
As mentioned previously, we can think of our multifilter UI as a
<form> with which to interact with our mixer. Adding a parent
<form> element to our UI also provides some additional benefits:
Reset buttons can be included within a form of filter groups to clear and reset all active UI and return the mixer to its default filter state (see
This is a very common UI pattern in search interfaces and allows the user to quickly return to full set of content without having to deactivate every UI element individually.
Similarly, if we want the ability reset an individual filter group, we can use individual forms as filter group elements, and nest reset buttons within them:
The default behavior of MixItUp MultiFilter is to trigger a filter operation whenever a control is clicked, or an input value changes. This allows the user to see the content change in real time as they interact with the UI.
By adding a submit button and changing the value of the
multifilter.parseOn configuration option from
'submit', we can delay the filter operation until the user has made their selection and is ready to search. The filter operation will then be triggered only when the user clicks the submit button.
Named Filter Groups
If you wish to interact with filter groups via the
.setFilterGroupSelectors() API method (see Mixer API Methods), we can name our groups by providing a value to
We can then target that group by its name when we call the API: