Checkbox filter

The most flexible module in the builder - a list of choices that can look like almost anything.

What you can build with it

It's worth knowing up front what this module is capable of, because the name undersells it. There are no style presets to choose from - every one of these is the same module with different parts switched on and arranged differently:

• A plain text list, with no checkboxes at all.
• The familiar checkbox list, with or without counts.
• A row of buttons, inline or full width.
• Buttons carrying an icon or an image.
• A grid of colour swatches, with the names shown, hidden, or on hover.

So the question when you open this module isn't which style to pick. It's which parts you want, and how they should sit together.

Data Source

First, what the list is made of. Data Source has two tabs, Taxonomy and Custom Field, and the Taxonomy tab groups what it offers into three sets.

Pick a source and its terms are listed with a checkbox each, so you can offer all of them or only some. Two small controls sit beside every term: one sets that term's own colour or icon, and the other marks it as a default - a term that starts out already selected when the page loads. You can set more than one default.

Using a custom field instead

A taxonomy already knows its own terms, so the list builds itself. A custom field doesn't - the values live on individual posts, and CAF has no way of guessing which of them you want offered. So with Custom Field selected you build the list yourself, in three steps.

• Choose the field, by its meta key.
• Choose the comparison - how a visitor's choice is matched against the stored value
• Add the values, one at a time, and each becomes an item in the filter.

Advanced Options holds a Meta Type for the field, which tells CAF what kind of value it's dealing with - worth setting when the values are numbers rather than text, so they're compared as numbers. Add Field adds a second field to the same module if one isn't enough.

Everything else works exactly as it does with a taxonomy. Each value can carry its own colour or icon, and can be marked as a default so it starts out selected - the same two controls, in the same place, doing the same job.

Icons and images per term

An icon can come from the built-in library, or you can upload your own as an SVG or PNG. The choice is made per term, not once for the whole list - so a few terms can carry library icons while others use artwork of your own, in the same filter.

Uploaded images are used at the size you supply them, so prepare them before uploading: consistent dimensions across the set, and no larger than they need to be. A mix of sizes shows up immediately as items that don't line up.

How visitors select

Allow Multiple Selection decides whether a visitor can pick several items or only one. Turn it off and the list behaves like a set of radio buttons - choosing something clears the previous choice.

Turn it on and a relation dropdown appears alongside, setting how the chosen terms combine: OR returns anything matching at least one, AND returns only what matches all of them. It's the same distinction described on Building the query, applied to what the visitor picks rather than what you set.

The four parts of an item

Each item in the list is assembled from up to four parts, and each has its own switch. Turn on all four, any two, or just one.

Two of them carry a further choice. Display As decides whether the second part shows as a Colour Swatch or as an Icon/Image - one or the other, never both on the same term. Whichever you choose sits in front of the term name or field value, so the visitor sees the swatch or icon first and the text after it. With Colour Swatch selected there's an extra option for the text: Show it, Hide it so the swatch stands alone, or put it in a Tooltip so the name appears on hover, which is how a colour grid stays compact without becoming a guessing game.

Show Count adds a Separator, deciding how the number is set apart from the text: brackets, a hyphen, nothing at all, or a custom character of your own.

Show More

A taxonomy with forty terms shouldn't fill a sidebar. Show More cuts the list to a set length and adds a link to open the rest.

Filter Label

The label above the module, with the same options as every other filter module: Enable turns it on, and Label Text is the wording. See Search filter for the same settings in context.

Arranging the parts

This is where the module earns its reputation. On the Design tab, Single Item holds a Layout group that doesn't arrange one thing - it arranges three pairings, each covering two parts of the item.

Each pairing gets the full set of flex controls: Direction for the order they run in and which comes first, Align X and Y for how they line up, and Gap for the space between. The alignment options are the same ones used throughout the builder - top, centre and bottom; left, centre and right; space between, space around and space evenly.

Only the pairings that apply are offered. With just a checkbox and text, Checkbox + Content is the only one there; switch on the icon and the count and all three appear.

Styling each part

The Design tab has three tabs of its own: Container for the block the list sits in, Single Item for the items themselves, and Show More for the link that opens the rest of a long list. Each carries the usual groups - Text, Sizing, Spacing, Background, Border and Box Shadow - so the show more link can look nothing like the items above it.

Inside Single Item, the groups go a level deeper still. Each one offers a target per part - Item for the whole thing, then Checkbox, Icon and Count individually - so the count can be smaller and lighter than the term name, or the checkbox a different colour from everything around it.

Alongside those sit three states: Default, Hover and Selected. Selected is the one that matters most here. It's what tells a visitor which choices are currently applied, and on a button or swatch layout - where there's no tick to give it away - it's the only thing that does.