Facet Filters
Facet filters let your users narrow down search results by clicking on categories, sliding price ranges, picking date ranges, and more. They appear as a sidebar next to your search results, just like the filters you see on any modern online store. For a full walkthrough of facet configuration with live examples, see the Faceted Navigation & Filtering guide.
What Are Facets?
Think of facets as smart filters that organize your search results into groups. When a user searches for "shoes," the facets might show them categories like "Running," "Casual," and "Formal," a price slider from $20 to $300, and a date filter to only see recently added products.
Facets are automatically generated from the data in your index. Opensolr counts how many results match each category, price range, or date bucket, and displays those counts next to each filter option. When a user clicks a filter, the results instantly update to show only matching items.
Widget Types
When you configure a facet, you choose which widget type it uses. The widget type determines how the filter appears on the search page and how users interact with it. There are four types:
List (Checkboxes)
Displays a list of values with checkboxes and result counts. Users click to select one or more values. Best for categorical data like type, brand, color, language. If there are many values, a "Show more" link opens a searchable dialog.
Slider (Numeric Range)
A dual-handle slider for numeric fields like price, rating, or size. Users drag the handles or type exact values in the input boxes. Opensolr automatically detects the minimum and maximum values from your data.
Date Range (Calendar)
Shows a date picker with start and end dates. Perfect for filtering by publication date, creation date, or any date field. Users click to open a calendar and select a range.
Hierarchical (Drill-Down)
A nested tree structure for categories that have subcategories. Users click a parent category to expand its children, drilling down level by level. Works like breadcrumb navigation but for filtering.
Configuring Facets
Setting up facets is done through the facet configuration dialog in your index settings. Here is how to do it, step by step:
- Open Facet Configuration — Go to your index settings and click the "Facet Filter Mapping" button. A full-screen dialog opens showing all available fields from your index. You can also retrieve the list of facetable fields programmatically via the Get Facetable Fields API.
- Enable Fields — Find the fields you want to use as filters. Toggle the Enabled switch to turn each one on. Only enabled fields will appear on the search page.
- Choose Widget Type — For each enabled field, select the widget type from the dropdown: List, Slider, Date Range, or Hierarchical. The widget type should match the data: use List for categories, Slider for numbers, Date Range for dates.
- Set Display Label — Enter the label that users will see on the search page. For example, the field
content_type_smmight be displayed as simply "Type". - Set Minimum Count — This controls the minimum number of results a facet value must have to be shown. Setting it to 1 (the default) means a value like "Formal (1)" will still appear. Setting it to 5 means values with fewer than 5 results are hidden, keeping the filter list clean.
- Drag to Reorder — The order of facets in the configuration table is the order they appear in the sidebar. Drag rows up or down to put the most important filters first.
- Save — Click Save to apply your configuration. The facets will appear on your search page immediately.
Built-in Facets
Every Opensolr index that uses the web crawler automatically has a set of built-in fields that can be used as facets. These are always available without any extra configuration of your data:
| Field | What It Contains | Suggested Widget |
|---|---|---|
| content_type | The type of page (e.g., article, product, FAQ, blog post) detected from structured data | List |
| language | The language of the page (en, fr, de, es, etc.) | List |
| creation_date | When the page was first crawled or its published date if specified | Date Range |
| price | Product price extracted from schema.org or JSON-LD markup | Slider |
| sentiment | The overall sentiment score of the page content (positive/negative) | List or Slider |
These fields exist in your index automatically. Just enable them in the facet configuration dialog and they will appear on your search page.
Custom Facets
Beyond the built-in fields, the Opensolr web crawler automatically extracts structured data from your pages and creates dynamic fields that can be used as facets. This structured data comes from:
- JSON-LD markup (schema.org) — product attributes, recipe ingredients, event dates, review ratings, etc.
- Meta tags — custom meta tags in your HTML head
- HTML tables and spec lists — key-value pairs from product specification tables
For example, if your product pages include JSON-LD with a brand property, the crawler creates a brand_sm field automatically. You can then enable it as a List facet labeled "Brand" in the facet configuration.
Dynamic fields use suffixes to indicate their data type: _sm for strings (shown as List facets), _fm for numbers (shown as Sliders), _dtm for dates (shown as Date Range), and _im for integers. These suffixes are added automatically by the crawler. For the complete field reference including all types and how text analysis works, see the Index Field Reference and How Text Analysis Works.
How Facets Behave on the Search Page
Once facets are configured, they appear on the search page in a sidebar. Here is how they work for your users:
- Click to filter — clicking a checkbox, moving a slider, or selecting a date range instantly filters the results. No need to press a separate "Apply" button.
- Active filter pills — each active filter appears as a small pill above the results. Users can see at a glance which filters are applied and click the X on any pill to remove it.
- Counts update dynamically — the number in parentheses next to each facet value updates to reflect the current filtered result set. For example, if you filter by "Running," the brand counts adjust to show only running shoe brands.
- "Show more" dialog — if a facet has many values (more than the initial display limit), a "Show more" link opens a searchable dialog where users can type to find and select specific values.
- Multiple filters combine — selecting filters from different facets narrows the results further (AND logic). Selecting multiple values within the same facet broadens it (OR logic). This is the standard e-commerce filtering behavior.
- Mobile-friendly — on small screens, the sidebar collapses into a toggle button. Tap the button to expand or collapse the filters.
Tips for Better Facets
Replace technical field names with user-friendly labels. Your users should never see content_type_sm — they should see "Content Type."
Drag your most popular or useful facets to the top of the configuration list. The first filter the user sees is the one they are most likely to use.
If a facet value has only 1 result, it clutters the sidebar without much benefit. A minimum count of 2 or 3 keeps the filter list clean and useful.
The more structured data (JSON-LD) your pages contain, the richer your facets will be. Adding schema.org markup for products, articles, or events gives you more fields to filter by. If you run an e-commerce site, see also Autocomplete & EdgeNGram Fields for complementary search features.
Match the widget type to the data. Price, rating, and size should always be Sliders. Category, brand, and color should always be Lists. Dates should always be Date Range.
Just because a field exists does not mean it should be a facet. Only enable fields that your users will actually want to filter by. Too many facets overwhelm users and slow things down.