Shared Props

Many facet families share the same logic even when their markup is different. The most important distinction is whether a prop belongs to the parent facet or to an authored option.

Parent Facet Props

These props apply to Select, SearchSelect, Radio List, and Checkbox List through FacetQueryProperties. Search Facet has matching props implemented in its own component file.

Prop	Applies to	Why it matters
target	All facet controls	Connects the control to the Facet Target with the same target ID.
argument_mode	Search and option facets when target_multiple_query_arguments is false	Chooses the single query mode.
target_multiple_query_arguments	Search and option facets	Switches from one query target to multi-argument behavior.
options_behavior	Select, SearchSelect, Radio List, Checkbox List	Controls unavailable option behavior after availability data changes.
show_counts	Select, SearchSelect, Radio List, Checkbox List	Enables dynamic result counts on options.
selection_mode	Select and SearchSelect	Chooses single or multiple selected values.
aria_label	Radio List and Checkbox List	Names the radiogroup or group for assistive technology.
default_label	Select and SearchSelect	Text shown when nothing is selected, and the built-in clear item label for Select.
placeholder	Search and SearchSelect	Text shown in the input before a value is typed.

Single-Argument Groups

When target_multiple_query_arguments is false, the selected argument_mode decides which group is active:

Group	Active when	Required values
default_query_argument	argument_mode is default	facet_key
meta_argument	argument_mode is meta	meta_key, meta_compare, meta_type
taxonomy_argument	argument_mode is tax	taxonomy, tax_field
date_argument	argument_mode is date	column
acf_relationship_argument	argument_mode is acf_relationship	meta_key

Multi-Argument Parent Props

When target_multiple_query_arguments is true, the parent facet uses query_argument_mappings.

Each row needs:

Prop	Meaning
mapping_key	Stable row key referenced by option value mappings.
argument_mode	Query mode for this mapped row.
facet_key	Used when row mode is default.
meta_key, meta_compare, meta_type	Used when row mode is meta.
taxonomy, tax_field	Used when row mode is tax.
column	Used when row mode is date.

For Search Facet, the typed input becomes the value for every mapped row. For option facets, each option supplies its own values through query_value_mappings.

Option Props

Select, SearchSelect, Radio List, and Checkbox List option components share these concepts:

Prop	Applies to	Meaning
content.value	Single-argument option mode	Value sent when the option is selected.
content.label	All option modes	Visible label and count base text.
metadata	All option modes	Optional key/value rows serialized for custom JavaScript integrations.
query_value_mappings	Multi-argument option mode	Per-option values keyed by parent mapping_key.
disabled	All option families	Prevents authored selection.
is_default	Select, Radio List, Checkbox List	Marks initial selection when no URL or runtime value already exists.
used_with_multiple_arguments	Option components	Shows mapping-driven authoring instead of manual content.value.
count_display	Option components	Chooses inline count text or a separate count span.

used_with_multiple_arguments is an authoring switch for option components. It should match the parent facet's multi-argument setup: enable it when the parent has target_multiple_query_arguments enabled and the option needs query_value_mappings.

Count Display

count_display supports:

Value	Behavior
inline	Runtime appends counts to the visible label text.
span	Runtime writes counts into a separate data-ome-facet-option-count span.

Use span when the count needs separate styling or layout. The PHP components include Etch preview count props for span mode so authors can style the counter before runtime data exists.

Reset Props

Radio List has built-in reset props:

Prop	Meaning
show_reset_option	Adds a reset choice before authored options.
reset_option_mode	Renders the reset choice as radio-style or button-style.
reset_label	Label for the built-in reset choice.

Reset Facet is a separate component. It clears all controls for the target rather than only one radio list selection.