Skip to content

Theming & Templates

When to Use

When customizing the HTML output of facets in your theme.

Decision: Available Templates

Template Theme Hook Purpose
facets-item-list.html.twig facets_item_list Container for facet items
facets-result-item.html.twig facets_result_item Individual result item
facets-views-plugin.html.twig facets_views_plugin Views integration wrapper

Decision: Template Variables — facets-item-list

Variable Type Description
facet FacetInterface The facet entity
items array Rendered result items
title string Facet label
list_type string 'ul' or 'ol'
attributes Attribute HTML attributes
wrapper_attributes Attribute Wrapper HTML attributes
empty string/array Message when no items
context array ['list_style' => 'links\|checkbox\|dropdown']

Decision: Template Variables — facets-result-item

Variable Type Description
value string Display text
raw_value string Backend value
show_count bool Whether to show count
count int Result count
is_active bool Currently selected
facet FacetInterface Parent facet entity

Pattern: Template Suggestions

Generated by facets_theme_suggestions_facets_result_item():

facets_result_item__WIDGET_TYPE__FACET_ID
facets_result_item__WIDGET_TYPE
facets_result_item

Example:

facets-result-item--links--category.html.twig  ← most specific
facets-result-item--links.html.twig
facets-result-item.html.twig                    ← fallback

Same pattern for facets_item_list:

facets-item-list--links--category.html.twig
facets-item-list--links.html.twig
facets-item-list--checkbox.html.twig
facets-item-list.html.twig

Pattern: Result Item HTML Structure

<!-- Active item -->
<li class="facet-item is-active">
  <a href="?f[0]=color:blue">
    <span class="facet-item__status js-facet-deactivate">(-)</span>
    <span class="facet-item__value">Blue</span>
    <span class="facet-item__count">(42)</span>
  </a>
</li>

<!-- Inactive item -->
<li class="facet-item">
  <a href="?f[0]=color:red">
    <span class="facet-item__value">Red</span>
    <span class="facet-item__count">(18)</span>
  </a>
</li>

Pattern: Block Preprocess

facets_preprocess_block() adds the widget type as a CSS class to facet blocks:

// Adds class like 'block-facet--links' or 'block-facet--checkbox'
$variables['attributes']['class'][] = 'block-facet--' . $widget_type;

Common Mistakes

  • Overriding without checking widget type — The facets_result_item template is shared across all widgets. Use widget-specific suggestions for targeted overrides.
  • Breaking JavaScript bindings — Widget JS relies on specific CSS classes (js-facet-deactivate, etc.). Preserve these when overriding templates.

See Also

  • Widgets — widget types and their CSS classes
  • Caching — cache debug output in templates
  • Reference: templates/