Facets
Provides faceted search interfaces for Drupal, allowing site builders to easily create and manage faceted navigation for Search API-based and core search displays.
facets
Install
composer require 'drupal/facets:^3.0'
Overview
The Facets module enables site builders to create and manage sophisticated faceted search interfaces without writing code. Facets are filters that allow users to narrow down search results by selecting specific criteria such as categories, dates, price ranges, or any indexed field.
The module provides a comprehensive plugin system with multiple widget types (links, checkboxes, dropdowns), numerous processors for transforming and filtering facet results, and flexible URL handling. It integrates seamlessly with Search API and Views, supporting both block-based placement and the newer exposed filters approach introduced in Facets 3.
Key capabilities include hierarchical facet support for taxonomies, multi-language support with automatic translation of entity labels, dependent facet conditions, customizable empty behaviors, and extensive caching with proper cache context handling. The module also supports REST exports through its facets_rest submodule.
Features
- Create facets from any Search API indexed field including taxonomies, entity references, dates, numbers, and text fields
- Multiple widget types: List of links, Checkboxes, Dropdown selector, and Array (for REST)
- Extensive processor system with 25+ built-in processors for sorting, filtering, and transforming facet results
- Hierarchical taxonomy support with expandable tree structures and parent-child relationships
- URL-based filtering with configurable URL aliases and query string handling
- Dependent facet conditions - show/hide facets based on other facet selections
- Empty behavior options: hide facet, show empty facet, or display custom text
- Multi-language support with automatic entity label translation
- Breadcrumb integration showing active facet selections
- Facets Summary submodule for displaying current search filters
- Range slider widgets through facets_range_widget submodule
- Searchbox filter widgets through facets_searchbox_widget submodule
- REST API support through facets_rest submodule for headless applications
- Views exposed filters integration through facets_exposed_filters submodule
- Soft limit feature to show/hide additional facet items with JavaScript
- Cache context support for proper caching of facet-filtered pages
- Event system for customizing facet URLs, query strings, and cache metadata
Use Cases
E-commerce Product Filtering
Create facets for product attributes like category, brand, price range, color, and size. Use the Range Widget submodule for price sliders. Enable hierarchy for nested categories. Configure AND/OR operators based on whether filters should be exclusive or additive.
Content Archive with Taxonomy Filters
Build a filterable content archive using taxonomy term facets. Enable 'Transform entity ID to label' processor to show term names. Use hierarchy for nested vocabularies. Add 'Hide non-narrowing results' to only show relevant filter options.
Search Results with Multiple Filter Types
Combine text facets (author, tags), date facets (publication date with granularity), and boolean facets (featured, published). Use dependent facets to show related filters only when parent facets are selected.
Headless/Decoupled Search API
Use the facets_rest submodule with Array widget to return facet data in REST API responses. Build custom frontend facet UIs while leveraging Drupal's Search API indexing and facet processing.
Multi-language Faceted Search
Enable 'Transform entity ID to label' processor which automatically loads translated entity labels. The module respects the current language context and provides proper cache contexts for language-aware caching.
Tips
- Use the new Facets Exposed Filters approach (facets_exposed_filters submodule) for new sites - it provides better Views integration
- Enable 'Sort by active state' processor to keep selected items at the top of the list
- Use URL aliases that are short but descriptive - they appear in URLs when facets are active
- Configure soft limits on links/checkbox widgets to show a manageable number of items with 'Show more' expansion
- Test facet behavior with browser caching disabled during development
- Use the facets_debug_cacheable_metadata setting to debug caching issues in development
Technical Details
Admin Pages 5
/admin/config/search/facets
Main administration page listing all configured facets grouped by their facet sources. Allows creating, editing, cloning, and deleting facets. Shows facet weight for ordering and provides quick access to facet source configuration.
/admin/config/search/facets/add-facet
Form for creating a new facet. Select a facet source (Views display), choose a field to facet on, and provide a name and machine name.
/admin/config/search/facets/{facets_facet}/edit
Main facet configuration form for editing widget, processors, and display settings.
/admin/config/search/facets/{facets_facet}/settings
Basic settings form for editing facet source, name, and field selection.
/admin/config/search/facets/facet-sources/{facets_facet_source}/edit
Configure facet source settings including URL processor and breadcrumb options.
Permissions 1
Hooks 1
hook_facets_search_api_query_type_mapping_alter
Alter the Facets Query Type mapping to customize how data types are handled in Search API based Facets
Troubleshooting 6
Enable the 'Transform entity ID to label' processor on the facet. Ensure the indexed field is an entity reference (not just the entity ID field).
Check that 'Hide facet when facet source is not rendered' is unchecked if displaying facets on pages without the search view. Verify the facet block is placed in a visible region.
Add a language filter to your Views query, or implement hook_search_api_query_alter() to restrict results to the current language.
Ensure your Views cache is set to 'Search API (none)' or a cache plugin that respects facet selections. The facets module adds appropriate cache contexts automatically.
Enable 'Ensure that only one result can be displayed' in facet settings to make dropdown behave as single-select.
Enable the 'Index hierarchy' processor on the Search API index for taxonomy fields. Enable 'Use hierarchy' on the facet and select Taxonomy as hierarchy type.
Security Notes 3
- The 'administer facets' permission grants full control over facet configuration - assign carefully
- URL aliases are sanitized to prevent XSS - only alphanumeric characters, dots, hyphens, underscores, and tildes are allowed
- Facet processors that display entity labels respect entity access - unpublished content labels are not exposed to unauthorized users