Facet Overview
Facets are controls that update one or more Facet Target result containers. A facet does not own the results. It sends a value for a shared target ID, the backend re-renders that target's stored Etch loop template, and the runtime swaps the returned markup into the target.
The basic structure is:
Search Facet, Select Facet, Radio List Facet, Checkbox List Facet, Map Address Facet, Map Radius Facet, Map Facet, Pagination Facet, Load More Facet, Reset Facet
|
| shared target ID
v
Facet Target
|
v
Etch loop slot + fallback slot
One target can be controlled by many facets. The E2E scenarios combine post_type, category_name, tag, meta queries, date queries, ACF relationship filters, pagination, reset, load more, and map bounds against the same target. The combined result is an intersection unless a specific mode documents a different behavior.
What Authors Configure
Every useful facet setup needs three decisions:
| Decision | Where it lives | What it controls |
|---|---|---|
| Target binding | Facet target and Facet Target target | Which result container receives updates. |
| Argument mode | Facet settings and mode-specific groups | Which query clause the selected value becomes. |
| Authored values | Option values, search input value, map bounds, pagination controls | The value sent for that query clause. |
The component family pages describe the markup and props for each family. The system pages explain how those props work together across families.
Component Families
- Facet Target stores and refreshes the result template.
- Search Facet sends text input values.
- Select Facet sends single or multiple selected option values.
- SearchSelect Facet sends searchable single or multiple option values.
- Radio List Facet sends one selected option value and can include a reset option.
- Checkbox List Facet sends multiple selected option values.
- Map Facet sends a geographic bounding box and reads Map POI data from the target loop.
- Map Address Facet sends selected address coordinates for proximity filtering.
- Map Radius Facet chooses the distance used with a same-target map address selection.
- Pagination Facet sends page offsets for a target.
- Load More Facet requests another batch for a target.
- Reset Facet clears all active filters for a target.
Accessibility Contract
Facet controls expose native or ARIA semantics for their interaction model. Search facets are named search inputs, select facets use listbox-style popups, search-select facets use editable combobox popups, radio list facets use a radiogroup, and checkbox list facets use grouped checkboxes.
Facet targets announce result changes politely. During refreshes, targets expose busy state, then the shared status region announces No results found, 1 result found, or the current result count.
Keyboard users can open dropdown facets with standard keys, close popups with Escape, move focus forward with Tab, activate buttons with Enter or Space, and update radio and checkbox facets without pointer input.
Start Here
Read these pages in order when building a facet interface:
- How Facets Work for the request and target lifecycle.
- Facet Events API for public control events, result lifecycle hooks, response metadata, and Map event recipes.
- Argument Modes for the exact meaning of each mode.
- Shared Props for props shared across select, search select, radio, checkbox, and search.
- Availability, Counts, and Options for dynamic option state.
- Recipes for codebase-backed examples from the E2E scenarios.