# Facet Overview

> How Oh My Etch facets connect controls to dynamic result targets.

<!-- Sources: src/Components/Facets/**; src/Components/Facets/Shared/**; src/Facets/FacetBlockInterceptor.php; src/Facets/FacetRestEndpoint.php; src/Testing/E2E/Facets/FacetsScenarioProvider.php; tests/e2e/components/facets/*.spec.ts -->

# 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:

```text
Search Facet, Select Facet, Radio List Facet, Checkbox List 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](./component-families/facet-target) stores and refreshes the result template.
- [Search Facet](./component-families/search-facet) sends text input values.
- [Select Facet](./component-families/select-facet) sends single or multiple selected option values.
- [SearchSelect Facet](./component-families/search-select-facet) sends searchable single or multiple option values.
- [Radio List Facet](./component-families/radio-list-facet) sends one selected option value and can include a reset option.
- [Checkbox List Facet](./component-families/checkbox-list-facet) sends multiple selected option values.
- [Pagination Facet](./component-families/pagination-facet) sends page offsets for a target.
- [Load More Facet](./component-families/load-more-facet) requests another batch for a target.
- [Reset Facet](./component-families/reset-facet) clears all active filters for a target.
- [Map Facet](./component-families/map-facet) sends a geographic bounding box and reads Map POI data from the target loop.

## Start Here

Read these pages in order when building a facet interface:

1. [How Facets Work](./how-facets-work) for the request and target lifecycle.
2. [Argument Modes](./argument-modes) for the exact meaning of each mode.
3. [Shared Props](./shared-props) for props shared across select, search select, radio, checkbox, and search.
4. [Availability, Counts, and Options](./availability-counts-and-options) for dynamic option state.
5. [Recipes](./recipes) for codebase-backed examples from the E2E scenarios.