Facet Types Reference

Complete configuration reference for all 14 built-in facet types. Every field listed here maps to a key in the facet's config JSON column.

checkbox radio dropdown button_group range date_range search autocomplete rating color toggle hierarchy sort active_filters

checkbox

Checkbox

Multi-select checkbox list. The most common facet type. Supports OR (any match), AND (all must match), and NOT (exclude) operators. Values come from the index table.

Config Field	Type	Default	Description
operator	OR \| AND \| NOT	OR	How multiple selections combine: OR = any match, AND = all must be present, NOT = exclude matching posts.
show_count	bool	true	Display item count beside each checkbox label.
show_more_count	int	5	Number of items visible before the Show More button appears. 0 = show all.
show_search	bool	false	Show a text input above the list to filter visible checkboxes client-side.
show_clear_button	bool	true	Show a Clear link to deselect all checkboxes in this facet.
hide_empty	bool	false	Hide items that have zero posts in the current filtered result set.
show_empty_as_disabled	bool	false	Show zero-count items as greyed-out disabled checkboxes instead of hiding them. Takes precedence over hide_empty.
max_selections	int	0	Maximum number of items that can be selected simultaneously. 0 = unlimited.
order_by	count \| name \| id	count	How to sort the checkbox list.
order	asc \| desc	desc	Sort direction.
min_count	int	0	Minimum post count an item must have to appear in the list.
hierarchical	bool	false	Render as an indented hierarchy using depth/parent data from the index table. Only meaningful for hierarchical taxonomies.
search_placeholder	string	Search…	Placeholder text for the client-side search input.
show_more_label	string	Show More	Label for the show-more button.
show_less_label	string	Show Less	Label for the collapse button.

AND operator works correctly for taxonomy sources — each selection generates a separate tax_query clause. For post_meta, AND generates multiple meta_query clauses. NOT uses NOT IN for taxonomy and meta sources.

radio

Radio

Single-select radio buttons. Only one value can be active at a time. Commonly used for sorting, status filters, or any exclusive-choice facet. Optionally shows an 'All' option to clear the selection.

Config Field	Type	Default	Description
show_all_option	bool	true	Prepend an 'All' radio option that clears the facet when selected.
all_label	string	All	Label for the All option.
all_count_display	total \| none	total	Whether to show the total post count beside the All option.
show_count	bool	true	Show post counts beside each option.
show_more_count	int	0	Items visible before Show More. 0 = show all.
show_search	bool	false	Show a filter-as-you-type input above the list.
show_clear_button	bool	false	Show an explicit Clear link.
hide_empty	bool	false	Hide zero-count options.
show_empty_as_disabled	bool	false	Show zero-count options as disabled.
order_by	count \| name \| id	count	Sort order for the options list.
order	asc \| desc	desc	Sort direction.
min_count	int	0	Minimum post count to appear.

dropdown

Dropdown

Native HTML select element. Supports single-select (default) and multi-select modes. In single-select mode, a placeholder or 'All' option is prepended. The same operator and source logic as checkbox applies.

Config Field	Type	Default	Description
multiple	bool	false	Allow selecting multiple options (renders as multi-select).
operator	OR \| AND \| NOT	OR	Operator for combining multiple selections.
max_selections	int	0	Max simultaneous selections in multi-select mode. 0 = unlimited.
placeholder	string	''	Placeholder text shown before any selection. Single-select only.
show_all_option	bool	false	Show an 'All' option that clears the filter. Single-select only.
all_label	string	All	Label for the All option.
show_count	bool	true	Show post counts in parentheses after each option label.
show_clear_button	bool	false	Show a Clear link next to the select.
hide_empty	bool	false	Exclude zero-count options from the list.
show_empty_as_disabled	bool	false	Show zero-count options as disabled.
min_count	int	0	Minimum post count to include an option.
order_by	count \| name \| id	count	Sort order.
order	asc \| desc	desc	Sort direction.

button_group

Button Group

Pill-style clickable buttons arranged in a wrap or horizontal-scroll layout. Works as either single-select or multi-select. Commonly used for size, category, or tag filters where visual buttons are preferred over checkboxes.

Config Field	Type	Default	Description
multiple	bool	false	Enable multi-select mode.
operator	OR \| AND \| NOT	OR	Combine operator for multi-select.
max_selections	int	0	Maximum selections in multi-select mode.
show_all_option	bool	false	Show an 'All' button that clears the filter. Single-select only.
all_label	string	All	Label for the All button.
show_count	bool	true	Show count badge on each button.
show_clear_button	bool	false	Show a Clear link below the buttons.
button_size	sm \| md \| lg	md	Button size preset.
button_layout	wrap \| scroll	wrap	wrap wraps to multiple lines; scroll keeps one row with horizontal scroll.
show_more_count	int	0	Items visible before Show More. 0 = show all.
show_more_label	string	Show More
show_less_label	string	Show Less
hide_empty	bool	false	Hide zero-count buttons.
show_empty_as_disabled	bool	false	Show zero-count buttons as disabled instead of hiding.
min_count	int	0	Minimum post count.
order_by	count \| name \| id	count	Sort order.
order	asc \| desc	desc	Sort direction.

range

Range Slider

A dual-handle slider for numeric ranges. Min and max bounds are automatically derived from the index table at render time and can be overridden in config. The slider generates a BETWEEN meta_query clause.

Config Field	Type	Default	Description
prefix	string	''	Text prepended to the value display, e.g. '$'.
suffix	string	''	Text appended to the value display, e.g. ' km'.
decimals	int (0–6)	0	Number of decimal places in input and display.
thousands_separator	string	''	Thousands separator: '' \| ',' \| '.' \| ' '.
decimal_separator	. \| ,	.	Decimal point character.
step	float (>0)	1	Slider step increment. Must be positive; supports fractional steps.
min_override	float \| ''	''	Force a minimum bound instead of reading from the index.
max_override	float \| ''	''	Force a maximum bound instead of reading from the index.
show_inputs	bool	true	Show numeric text inputs beside the slider.
show_slider	bool	true	Show the graphical slider. Can be disabled to show inputs only.
show_clear_button	bool	true	Show a Clear link to reset to full range.
value_display	range \| separate \| none	range	How to display the current value: 'range' = '$25–$200', 'separate' = two values, 'none' = hidden.
min_label	string	Min	Label for the minimum input.
max_label	string	Max	Label for the maximum input.

WooCommerce price fields (wc:price, wc:sale_price, wc:regular_price, wc:rating, wc:weight) are automatically mapped to their internal meta keys (_price, _wc_average_rating, _weight, etc.).

date_range

Date Range

Filter posts by a date range. Two modes: date picker inputs (from/to) or preset quick-select buttons (Last 7 Days, This Month, etc.). Works with post_date, post_modified, and any date-formatted meta field.

Config Field	Type	Default	Description
preset_mode	bool	false	Show preset buttons instead of date picker inputs.
from_label	string	From	Label for the start date input.
to_label	string	To	Label for the end date input.
min_date	YYYY-MM-DD \| ''	''	Earliest selectable date. Empty = no constraint.
max_date	YYYY-MM-DD \| ''	''	Latest selectable date. Empty = no constraint.
date_format	string	Y-m-d	PHP date format for display and parsing.
show_clear_button	bool	true	Show a Clear link to reset the date range.

Built-in presets: last_7_days, last_30_days, this_month, last_month, last_3_months, last_6_months, this_year, last_year, all_time, custom. For post_date sources the query uses date_query; for meta fields it uses meta_query with BETWEEN and type=DATE.

search

Search

Text input for searching posts. Multiple search modes are supported: full-text WordPress search, field-scoped search using WP 6.2+ search_columns, post meta LIKE search, and taxonomy term name search.

Config Field	Type	Default	Description
search_type	string	full_text	full_text (WP native 's'), title, content, excerpt, title_content (WP 6.2+), post_meta (meta LIKE), taxonomy (term name search).
meta_key	string	''	Required when search_type=post_meta. The meta_key to search with LIKE.
taxonomy	string	''	Required when search_type=taxonomy. Taxonomy slug to search term names in.
min_characters	int (≥1)	2	Minimum characters before the search fires.
debounce	int (≥50)	400	Milliseconds of idle time after keypress before firing the search.
placeholder	string	''	Input placeholder text.
show_icon	bool	true	Show a search icon inside the input.
icon_position	left \| right	left	Position of the search icon.
show_clear	bool	true	Show an × button to clear the search input.

For taxonomy search, Grid Panda calls get_terms(['search' => $query]) and builds a tax_query with up to 200 matching term IDs. For title/content/excerpt scoping, WordPress 6.2+ search_columns support is required — older WP versions fall back to full_text.

autocomplete

Autocomplete

AJAX-powered typeahead input. As the user types, it fetches matching values from GET /wp-json/gridpanda/v1/facets/{id}/autocomplete?q=... and displays them as a dropdown. Supports single and multi-select (tag input).

Config Field	Type	Default	Description
placeholder	string	Type to search…	Input placeholder text.
min_characters	int (≥1)	2	Characters needed before the first AJAX request fires.
debounce	int (≥50)	300	Delay in ms after last keystroke before the request fires.
multi_select	bool	false	Allow selecting multiple values as tags.
max_tags	int	10	Maximum tags in multi-select mode. 0 = unlimited.
operator	or \| and	or	Combine multiple selections with OR or AND.
include_children	bool	true	Include child terms when filtering by taxonomy. Passed to tax_query.
show_count	bool	false	Show post count beside each suggestion in the dropdown.
show_clear_button	bool	true	Show a Clear button to remove all selections.

rating

Rating

Star rating filter for numeric rating fields. Typically used with WooCommerce's _wc_average_rating meta key. Supports 'and up' mode (show all posts rated X or higher) or exact tier matching. Tier counts are accumulated from the index.

Config Field	Type	Default	Description
max_stars	int (1–10)	5	Maximum rating level. Controls how many rating tiers are shown.
min_rating	int (1–max_stars)	1	Minimum rating tier to display as an option.
filter_mode	gte \| exact	gte	gte = show posts rated at or above the selected value. exact = show posts where the rating floor equals the selection.
layout	stacked \| inline	stacked	stacked = one tier per row; inline = all tiers in one row.
star_icon	star \| heart \| circle \| diamond \| fire \| thumbsup \| custom	star	Icon to use for rating display.
custom_icon	string	''	HTML/SVG string used when star_icon=custom.
label_format	and_up \| stars \| icon_only \| custom \| none	and_up	How to label each tier: '3 & up', '★★★', icons only, custom template, or no label.
custom_label	string	{n} and up	Template for label_format=custom. {n} is replaced with the tier number.
show_count	bool	true	Show accumulated post count beside each tier.
show_clear_button	bool	true	Show a Clear link.

The rating index must contain decimal values (e.g., 4.5, 3.2). Grid Panda floors each value to determine its tier and accumulates counts upward — the count for tier 3 includes all posts rated 3.0 and above.

color

Color Swatch

A grid or list of color swatches for visual color filtering. Each swatch maps a facet value (e.g. term slug 'red') to a hex color code or CSS gradient. Unmapped values are rendered without a color background.

Config Field	Type	Default	Description
color_map	object {slug: '#rrggbb'}	{}	Map of facet value slugs to hex color codes.
gradient_map	object {slug: 'linear-gradient(...)'}	{}	Map of slugs to CSS gradient strings for multi-color swatches.
operator	or \| and	or	Combine multiple swatch selections. AND only meaningful for taxonomy sources.
hide_empty	bool	false	Hide swatches with zero post counts.
only_mapped	bool	false	Show only swatches that appear in color_map or gradient_map — hide unmapped values.
swatch_size	CSS length	36px	Width and height of each swatch.
swatch_shape	circle \| square \| rounded	circle	Shape of the color swatches.
layout	grid \| list	grid	Grid wraps multiple swatches per row; list shows one per row with label.
show_label	bool	true	Show the value label below or beside the swatch.
show_count	bool	false	Show post count beside each swatch.
show_tooltip	bool	true	Add a title attribute to show label on hover.
show_clear_button	bool	true	Show a Clear link.
selection_indicator	checkmark \| ring \| border \| dot	checkmark	How to visually indicate a selected swatch.
selection_color	CSS color \| ''	''	Color of the selection indicator. Empty = auto-contrast.

toggle

Toggle

A binary on/off switch. When toggled on, filters posts where the configured field equals on_value. When off, no filter is applied. Common use cases: In Stock only, Featured posts, On Sale items.

Config Field	Type	Default	Description
on_value	string	'1'	The field value that the toggle filters for when active. For a boolean meta field this is typically '1'; for taxonomy it is a term slug.
off_value	string	'0'	Display-only label for the inactive state. Not used in queries.
label_on	string	Yes	Label shown in the active state.
label_off	string	No	Label shown in the inactive state.
show_label	bool	true	Show the label beside the toggle switch.
show_count	bool	false	Show the count of matching posts beside the label.
show_clear_button	bool	false	Show a Clear link.

For taxonomy sources, the toggle generates a tax_query for the slug in on_value with include_children=false. For post_meta sources it generates meta_query compare='='. For recognized post fields (post_status, post_author, post_type, etc.) it sets the field directly in WP_Query args.

hierarchy

Hierarchy

Collapsible tree filter for hierarchical WordPress taxonomies (categories, product categories, etc.). Uses the depth and parent_id columns in the index table to reconstruct the tree without extra DB queries.

Config Field	Type	Default	Description
max_depth	int	0	Maximum depth levels to display. 0 = show all levels.
include_children	bool	true	When a parent term is selected, also include child term posts in the query result.
expand_mode	all \| collapsed \| first	all	Initial expand state: all = expand everything, collapsed = all collapsed, first = only first level expanded.
show_count	bool	true	Show post counts beside each term.
show_clear_button	bool	true	Show a Clear link.

Only works with taxonomy sources backed by hierarchical taxonomies. The tree is built in two passes: first all nodes are mapped by slug, then parent-child relationships are wired using the index's parent_id (WP term_id) → parent slug resolution.

sort

Sort

A sort-order control rendered as a dropdown, radio buttons, or pill buttons. Unlike other facet types, Sort does not filter posts — it modifies the WP_Query orderby and order arguments. Each option is fully configurable.

Config Field	Type	Default	Description
render_type	dropdown \| radio \| button_group	dropdown	How to render the sort control.
default_sort	string	newest	The sort option slug to use when no selection is active.
relevance_on_search	bool	true	Automatically switch to relevance sort when a search facet is active.
show_placeholder	bool	false	Show a placeholder option in dropdown mode.
placeholder	string	— Sort by —	Placeholder label for dropdown mode.
sort_options	array of objects	see defaults	Array of sort option definitions. Each object must have: value (slug), label, orderby, order (ASC\|DESC). Optional: meta_key (for meta_value/meta_value_num orderby), meta_type (NUMERIC\|DECIMAL\|DATE\|DATETIME\|BINARY), icon.

Default sort_options provide: newest (date DESC), oldest (date ASC), title_asc (title ASC), title_desc (title DESC). Any WP_Query orderby value is supported — date, title, modified, comment_count, ID, rand, meta_value, meta_value_num, etc.

active_filters

Active Filters

Displays the currently-active filter selections as removable pills. This is a pure UI widget — it adds nothing to the WP_Query and does not need indexing. The pills are populated by JavaScript after the page loads and update dynamically as filters change.

Config Field	Type	Default	Description
show_clear_all	bool	true	Show a 'Clear All' button that removes all active filters at once.
show_facet_label	bool	true	Prefix each pill with the facet name (e.g. 'Color: Red').
clear_all_label	string	Clear All	Label for the Clear All button.

Place this facet at the top of your filter sidebar or above the grid for best UX. It renders an empty container server-side and is fully populated by the Grid Panda JS runtime after load.

← Facets Grids →