Skip to content

Installation & Setup

When to Use

When setting up Facets on a Drupal site with Search API.

These guides document Facets 3.0.6, the current stable tag on the 3.x branch. Where they say "3.x" they mean a behaviour that holds across the branch, not a looser version claim.

Pattern: Installation

# Install Facets (requires Search API)
composer require drupal/facets drupal/search_api

# For exposed filters integration (recommended):
composer require drupal/better_exposed_filters

# Enable modules
drush en search_api facets

# For exposed filters:
drush en facets_exposed_filters better_exposed_filters

# For summary (active filter breadcrumbs):
drush en facets_summary

# For range sliders:
drush en facets_range_widget

Pattern: Prerequisites Checklist

Step Action Where
1 Create a Search API server /admin/config/search/search-api
2 Create a Search API index /admin/config/search/search-api/add-index
3 Add fields to the index Index → Fields tab
4 Index the content Index → View tab → "Index now"
5 Create a View using the index Views → Add (select the search index as source)
6 Save the View Must save before adding facets
7 Create facets /admin/config/search/facets/add-facet

Decision: Block-Based vs Exposed Filter Facets

Approach When to Use AJAX Setup Complexity
Exposed Filters (3.x recommended) Standard search pages with AJAX Yes (native Views AJAX) Low — add as Views filter criteria
Block-based (2.x style) Custom layouts, Layout Builder, sidebars No Medium — place blocks in regions
REST Headless/decoupled frontends N/A Medium — configure REST display

Pattern: Admin Routes

Route Purpose
/admin/config/search/facets Facet listing and management
/admin/config/search/facets/add-facet Create new facet
/admin/config/search/facets/{facet}/edit Edit facet configuration
/admin/config/search/facets/facet-sources/{source}/edit Configure facet source

Common Mistakes

  • Not saving the View first — You must save the View before facets can see it as a source. If you add fields and don't save, facets won't find the View display.
  • Forgetting to index content — After adding fields to the index, you must reindex. Facets only show results for indexed content.
  • Wrong Search API server — For development, use the "Database" server. For production, use Solr or Elasticsearch. Some facet features (hierarchy, range) work better with Solr.

See Also