[woocommerce_product_filter_attribute] shortcode shows a live Product Attribute Filter.
This live filter displays the terms related to a product attribute. Used within appropriate context*, the customer can click a term and the page will show products that are related to it.
Typical examples are Color, Size, Brand, … in the case of a Size attribute, the filter would offer the different size options like XS, S, M, L, XL etc.
*This shortcode must be used within appropriate context, i.e. where products are displayed, as for example on a shop page. As with all live product filters that this extension provides, this filter field is used to refine the selection of products and reduce it to a set that contains only those that match what the customer is looking for.
Use this filter shortcode on a shop page or in conjunction with the
[woocommerce_product_filter_products] shortcode on any page. The
[woocommerce_product_filter_products] shortcode displays the products as if you were on the shop page and in combination with the filter shortcode, it updates them dynamically when the customer clicks on any of the terms offered.
You can use the following shortcode attributes to customize the shortcode. It is required to indicate at least the product attribute (or the taxonomy), for example:
- attribute – This is required and must indicate the product attribute to be used for this filter. Alternatively, the taxonomy can be indicated.
- taxonomy – Indicate the exact name of the product attribute taxonomy.
- show_heading – Whether to display the heading for this filter. “yes” or “no”
- heading – You can provide a customized heading here or omit it to use the default. The heading will be displayed when there are terms to show, it will be hidden when there are none.
- heading_no_results – You can provide the text of an alternative heading to be displayed when there are no results.
- style – How to display the terms, “list” or “inline” or “select” or “dropdown”.
- size – Applies with
style="select"and determines the size of the control that is displayed.
- show_thumbnails – Whether to show thumbnails for the terms, “yes” or “no”.
- show_selected_thumbnails – Available when “dropdown” is used as style. Enabled by default or using “yes”, displays thumbnails also for the selected terms. Using “no” disables it.
- show_names – Whether to show the names of the terms, “yes” or “no”.
- show_count – Whether the number of related products per term will be shown, “yes” or “no”.
- hide_empty – Whether to automatically hide terms that have no related products.
- number – If a number is provided through this attribute, it limits the number of terms shown. If omitted, all applicable terms are shown.
- height – Used with
style="dropdown". If left empty, the choices of the dropdown are shown below when the field gains focus. If a plain number is input, e.g. 5, the Dropdown will adopt a fixed height to show the indicated number of entries. If a number with a CSS unit* is used, e.g. 120px, the Dropdown will adopt a fixed height as per the indicated unit. *Allowed CSS units: px, mm, cm, in, pt, pc, em , ex, ch, rem, vw and vh.
- toggle – Hide the filter component when it has no options, “yes” (by default) or “no”.
- toggle_widget – Hide the widget when the component has no options, “yes” (by default) or “no”.
- orderby – Used to determine the order in which the terms are shown, “count”, “id”, “term_order” (default), “name”, “slug” or “description”.
- order – Sets ascending or descending order, “asc” (default) or “desc”.
- filter – Whether live filtering should be enabled, “yes” or “no”.
- multiple – Whether to let visitors select more than one term, “yes” or “no”.
- show – This will determine whether all terms are shown (with “all”) or only those that are within the context of the selected term (with “set”).
- include – You can indicate the terms that should be included here. If left empty, all terms are displayed. Indicate terms by ID, slug or name and separated by comma.
- exclude – Indicate the terms that should be excluded here by ID, slug or name and separated by comma. If include is provided, it overrides this shortcode attribute completely – use either of them but not both.
- none_selected – The text displayed when no term is selected. Used with
The advanced attributes should be left at their defaults unless there is the need to approach a specific case with this filter.
- heading_id – This sets the ID of the heading element.
- heading_class – This sets the class of the heading element.
- heading_element – Used to determine which HTML tag is used as the heading element.
- container_id – This sets the ID of the filter’s main div container element.
- container_class – This adds to the class of the filter’s main div container element.
The shortcode supports global product attributes. Instances cannot be used to filter custom product attributes. We strongly recommend to only use global product attributes as the proper method to relate any product to its attributes, including those that are used on a single instance of a product. To learn more about how to create and use global product attributes, please refer to this section on Product Attributes.