Taxonomy Filter Block

The Taxonomy Filter Block turns your taxonomy terms into filterable options. Display as checkboxes or in a select box.

How to Find It?

With ACF Engine installed the Taxonomy Filter is available in any instance of Gutenberg. Using the forward slash search method start typing “tax” or “fil” to bring it up on the list of available blocks.

Searching “tax” to find the Taxonomy Filter block in Gutenberg.

Block Options

Taxonomy (taxonomy)

Taxonomy registration key. This is usually a single word all lowercase such as the default WordPress taxonomy “category” and “post_tag”.

When the taxonomy key has 2-words it may be underscored such as “post_tag” or some 3rd-party registered taxonomies may use hyphenation such as “product-category”. If you have registered a custom taxonomy using the ACF Engine taxonomy registration feature, this key should match the key you used in the taxonomy registration form at ACF Engine > Taxonomies > Taxonomy Editor.

Style (style)

Display style choice. Options include “Checkboxes”, “Select”. As the name implies, checkboxes will be rendered as checkboxes with a label. By default these checkboxes will be rendered in a horizontal row at larger screens, and then stacked at smaller screen sizes. You can also use the Stack Options setting documented below to force the items to stack vertically even when there is space for a horizontal row display.

A select box is a good alternative in some situations. Generally the select box takes up less UI space and is practical and easy to use. It is also a singular selection option, which means it fits better for filters where you expect the user to look at each option individually. On a real estate site for instance a “Property Type” filter might be suitable for select style rendering.

Default value: Checkboxes.

Stack Options

Render the filter options as a vertical stack. With this option set to “Yes” the options will always be stacked even if there is enough horizontal space to render them in a row. By default stacking only occurs based on breakpoint. This option is usually used when the filter is in a sidebar or other width constrained container where stacking the options will look better at any screen size.

Show Heading (show_heading)

Render a heading (h3 tag) above the taxonomy filter. This option is provided for convenience, but for more control you can use a Gutenberg heading block separately from the filter block which enables more style and layout options. If you activate this option you will be able to set the text for the heading using the Heading (heading) option.

Heading (heading)

Text for the heading (h3 tag) rendered above the filter. This option is only shown if you have the Show Heading (show_heading) option set to “Yes”.

Block Renders

Taxonomy Filter Block settings in Gutenberg.
Filter options rendered as checkboxes.

Related Blocks & Dependencies

A taxonomy filter needs a Loop Block to filter. The post type rendered in the Loop Block needs to have an association to the taxonomy used in the filter. This is a potential cause of failure during filtering if you have setup a custom post type and custom taxonomy, make sure that your taxonomy is associated to your post type, and that you have testing posts that use terms from the taxonomy.

The Taxonomy Filter block is part of ACF Engine’s Data Collection Block Suite. This block suite includes another filtering block that is a bit more complex, called the Meta Filter block.