Facet Types

Facet Types

The full catalog of facet types HOF will support at 1.0.

Warning

Pre-alpha. All facet types listed here are planned. The first four ship in alpha; the rest land through beta and 1.0. Check Roadmap for live status.

quick reference

Type	Best for	Ships in
Checkbox	Multi-select categories, tags, attributes	🚧 Alpha
Radio	Single-select choice from a fixed list	🚧 Alpha
Dropdown	Long lists, space-constrained UIs	🚧 Alpha
Range Slider	Price, weight, numeric meta	🚧 Alpha
Date Range	Events, posts by published date	🚧 Beta
Search	Free-text within the result set	🚧 Beta
Hierarchy	Nested taxonomies	🚧 Beta
Color Swatch	Visual attribute selection	🚧 Beta
Toggle	Boolean filters	🚧 1.0

pick the right type

flowchart TD
    Start([Need to filter on...]) --> KindQ{What kind of data?}
    KindQ -->|Free text| Search[Search]
    KindQ -->|Numeric range| Slider[Range Slider]
    KindQ -->|Dates| DateRange[Date Range]
    KindQ -->|Discrete values| MultiQ{Multi or single select?}
    MultiQ -->|Single, boolean| Toggle[Toggle]
    MultiQ -->|Single, from list| ListSize{How many options?}
    ListSize -->|Few, 2-6| Radio[Radio]
    ListSize -->|Many| Dropdown[Dropdown]
    MultiQ -->|Multiple| VisualQ{Visual choices?}
    VisualQ -->|Yes, colors/swatches| Swatch[Color Swatch]
    VisualQ -->|No| HierQ{Nested structure?}
    HierQ -->|Yes| Hierarchy[Hierarchy]
    HierQ -->|No| ChkOrDrop{Short list?}
    ChkOrDrop -->|Yes, under ~20| Checkbox[Checkbox]
    ChkOrDrop -->|No, long list| Dropdown

Loading

common config shape

Every facet type shares a base schema. Type-specific options go under behavior and ui:

{
  "name": "product_category",
  "type": "checkbox",
  "label": "Category",
  "source": "taxonomy:product_cat",
  "behavior": { /* type-specific logic */ },
  "ui": { /* type-specific UI options */ }
}

shared fields

Field	Type	What
name	string	Unique slug. Becomes the URL param: ?_hof_<name>=...
type	string	One of: checkbox, radio, dropdown, range_slider, date_range, search, hierarchy, color_swatch, toggle
label	string	Display label in the frontend UI
source	string	Data source. Format: taxonomy:<slug> | meta:<key> | post:<field>
behavior	object	Type-specific query and matching logic
ui	object	Type-specific rendering options

shared behavior

All facets share:

• URL state. Every change updates the URL. Shareable, back/forward works.
• AJAX-first, no-JS fallback. Forms still submit if JavaScript fails.
• A11y baseline. Keyboard navigable, ARIA-labeled, screen-reader friendly.
• Translations. Labels run through __() and are translatable.
• Hooks. Every facet type fires hof_facet_<type>_* filters for customization.

see also

• Core Concepts — what's a facet, indexing, URL state
• Architecture — how facets are registered and rendered
• Developer Guide — extending HOF with custom facet types