Facet Types

Facet Types

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

Note

Pre-alpha. Some facet types are shipped (experimental); others are still planned. The Roadmap has the live status.

quick reference

Type	Best for	Status
Checkbox	Multi-select categories, tags, attributes	✅ Shipped
Range Slider	Price, weight, numeric meta	✅ Shipped
Search	Free-text within the result set	✅ Shipped
Color Swatch	Visual attribute selection	✅ Shipped
Swipe Deck	Touch-first vibe filtering	✅ Shipped
2D Slider	Two numeric ranges as one gesture	✅ Shipped
Ask	Conversational, multi-turn natural-language → editable filter chips (BYOK)	✅ Shipped
Radio	Single-select choice from a fixed list	🚧 Alpha
Dropdown	Long lists, space-constrained UIs	🚧 Alpha
Date Range	Events, posts by published date	🚧 Beta
Hierarchy	Nested taxonomies	🚧 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