FacetWP Range List - WordPress Plugin

How to Configure FacetWP Range List for Numeric Ranges in WordPress

FacetWP Range List is not just another generic site filter. Its job is to turn a numeric field into clear, ready-made choices. In this guide, you'll learn how to prepare your data, define ranges, choose the right interface type, place the filter next to a post or product listing, and verify that it works properly on the front end.

This article is written for site owners, webmasters, and developers who already understand the general purpose of filtering but want to configure Range List specifically without leaving gaps: why ranges sometimes overlap, why re-indexing matters, when to enable "ghost" options, how to avoid breaking WooCommerce filtering behavior, and what to do if the filter appears empty.

We will not cover purchasing, license activation, or unofficial ways of obtaining the product. The practical goal is different: to build a working filter for price, area, weight, age, rating, or any other numeric value, and then integrate it safely into a results page.

What Problem a Range List Solves

Range List adds a separate facet type to FacetWP for predefined numeric ranges. A standard taxonomy filter shows values that already exist as terms, and a slider asks the visitor to move handles manually. Range List works differently: the administrator defines the value bands in advance, and the visitor selects one or more human-friendly groups.

In practice, this is especially useful when the underlying value is precise, but users do not need that level of precision. A product price may be stored as 129, a property size as 48.6, an item weight as 3.2, or a participant age as 37. Most visitors are not looking for "exactly 48.6 square meters"; they are choosing "up to 50," "50-80," or "80 and above." FacetWP Range List fills that gap between an exact number and an intuitive selection.

The plugin does not create data for you. It reads the numeric value from a FacetWP data source: a custom field, attribute, post property, or another supported source. Each post is then matched to one or more ranges if its value falls within the specified boundaries. That means the quality of the outcome depends not only on the facet settings, but also on how consistently the source fields are filled in.

When Range List Is Better Than a Slider

A slider works well when visitors need to set their own lower and upper limits. For example, someone may want to move the price range from 120 to 340 or select property size manually. But on many sites, that level of freedom makes filtering harder: users see too many small states, results change with every movement, and on mobile the slider is not always convenient.

Range List is stronger when the administrator already knows the logical groups:

• A product catalog with price bands such as "up to 50," "50-100," and "100 and above."
• Real estate listings by square footage or bedroom count, where visitors choose familiar categories.
• An equipment catalog filtered by weight, power, volume, or other numeric specifications.
• An events or participant directory where a numeric value should be presented as an age group or skill level.
• Recipes, products, or services where predefined thresholds matter more than free-form input.

The key difference from a regular list is that the selected option does not have to match the exact value in the database. The visitor sees a clear label, and Range List maps it to a numeric interval behind the scenes.

When This Facet May Be Unnecessary

Range List is not something to enable just because a page "needs a filter." If the field is text-based, contains measurement units, spaces, currency symbols, or commas instead of decimal points, the facet will not work reliably as a numeric filter. The data needs to be normalized first. If users need to enter arbitrary values, Number Range or Slider may be a better fit. And if the values are really terms, categories, or attributes without numeric meaning, standard Checkboxes, Radio, Dropdown, or fSelect will be simpler.

Another case where Range List may be excessive is a very small result set. If a page only has a few entries and each group returns a single item, the range filter can make the catalog feel empty. In that case, check the numbers first: how many entries fall into each planned group, and whether half of the ranges will always stay empty.

Practical rule: Choose Range List when exact numbers already exist in your data, but visitors are better served by selecting predefined ranges. If the numbers are not filled in yet or the logical thresholds are still unclear, prepare the data first and create the facet afterward.

What to Check in Your Data Before Installation

The most common mistake with a range filter happens before the add-on is even installed: the administrator assumes the products or posts already have a "price," "area," or "age," but in the database those values are not stored as clean numbers. For Range List, that is critical. The facet expects a numeric source because it compares each record's value against the Min and Max boundaries.

Before installation, it is worth doing a quick audit. It saves more time than troubleshooting an empty facet later.

Check the Value Source

Open a few posts or products that should be included in filtering and see where the required value is stored. It might be an ACF field, the standard WooCommerce Price field, a custom meta field, a numeric attribute, or another source that appears in the FacetWP dropdown. What matters is not just that the field exists, but that it is filled in for enough records.

If you are using Advanced Custom Fields, choose the field in FacetWP under the ACF heading, where the field group name appears next to it. That helps you avoid selecting a similarly named technical meta field that may be indexed differently. For WooCommerce, price and other commerce-related fields are available through separate WooCommerce sources if FacetWP detects the relevant integration.

Clean Up the Number Format

For ranges, values should be stored without currency symbols, text, or thousands separators. Not $1,200, not 1 200 m2, not from 1200, but 1200. For decimals, use a period, for example 48.6. The official Range List documentation specifically notes that decimal boundaries must use periods, not commas, and should not include spaces or other characters.

If your site already contains older records with inconsistent formats, standardize the data first. For a small catalog, you can do that manually. For a large one, it is better to prepare an import or migration on a staging copy of the site, then run a full FacetWP re-index.

Evaluate the Groups You Plan to Use

Your ranges should reflect real selection groups, not just neat arithmetic. If 90% of your products cost less than 100, ranges like "up to 500," "500-1000," and "1000 and above" will be almost useless. If property sizes run from 20 to 220 square meters, you can make the ranges tighter in the most common zone and broader at the edges. If your values include decimals, decide whether users actually need that level of granularity.

For each planned group, it helps to define three things: the label, the lower boundary, and the upper boundary. The label should be understandable without knowing the database. The boundaries should be technically precise. For example, the label "Up to 100" may correspond to an empty Min and a Max of 100. The label "100-200" may start at 100 and end at 200. But if those boundaries overlap, a record with the value 100 may fall into both groups, because Range List treats both the lower and upper limits as inclusive.

Prepare the Listing Page

FacetWP cannot filter empty space. The page must contain a listing of posts, products, or custom post types that FacetWP can recognize as a supported template. That may be a standard WooCommerce archive, Listing Builder, blocks, Elementor, Beaver Builder, Bricks, a custom WP_Query, or another supported setup. What matters is that the page contains one FacetWP-compatible listing, because FacetWP needs to know which result set to update.

If the listing is built with custom code, verify in advance that the results container follows FacetWP's markup rules and that the query does not conflict with the main WordPress query flow. If the listing is built with a page builder, confirm that the FacetWP integration supports that specific widget or block. For WooCommerce, it is usually easier to test first on the standard product archive and only then move the filter into a more complex layout.

Installing the Add-On and Running the First Check in the Admin Panel

Range List is an add-on for FacetWP, so it does not replace the main plugin. FacetWP must already be installed and active on the site before you add Range List. Once enabled, a new facet type appears in the facet type list and can be selected when creating or editing a facet.

Do not mix installation with full catalog configuration. The cleanest order is simple: enable the add-on, create one test range facet, rebuild the index, and only then refine the boundaries, appearance, and interactions with other facets.

Basic Installation Sequence

1. Make sure the main FacetWP plugin is already active and available under Settings > FacetWP.
2. Install Range List as a separate ZIP plugin via Plugins > Add Plugin > Upload Plugin or through the standard WordPress plugin upload flow.
3. Activate the add-on in the plugin list.
4. Go to Settings > FacetWP and open the facets tab.
5. Create a new facet or open an existing test facet.
6. Confirm that Range List is available in the facet type field.

If the type does not appear, first verify that both plugins are active: the main FacetWP plugin and Range List. Then confirm that your FacetWP core version meets the add-on requirements. The FacetWP add-ons page lists the required FacetWP version for Range List, so an outdated core plugin may fail to expose the new type or behave unpredictably.

Your First Test Facet

For the first check, there is no need to build a perfect price structure right away. Create one simple facet with a clear internal name, such as price_range or area_range. In FacetWP, the internal name is used in the shortcode, URL, and JavaScript data, so it is best to stick to Latin letters, numbers, and underscores. Do not name the facet name, length, method, or other problematic words that may overlap with reserved variables.

Select a numeric Data source and add two or three rows under Ranges. For example, for a test product catalog:

• Up to 50: leave Min empty and set Max to 50.
• 50-100: leave Min empty and set Max to 100 if you want the range to continue automatically from the previous maximum.
• 100 and above: leave both Min and Max empty in the last row if you want an open-ended range continuing from the previous boundary.

After saving, click Re-index. In FacetWP, this is not a formality: the index stores prepared facet data in a separate table, and without updating it, your new ranges may not produce any selectable options.

How to Tell Quickly Whether the Add-On Is Working

After indexing, place the facet on a test page next to the results listing. The simplest option is a shortcode such as [facetwp facet="price_range"], where the name inside the quotes matches the facet's internal name. If the results listing is built with Listing Builder, the page may also include the listing template shortcode nearby. If you are placing the filter in a theme sidebar, you can insert the shortcode into a Shortcode block or a suitable widget.

On the front end, you should see a list of ranges, radio buttons, a dropdown, or fSelect, depending on the chosen UI type. Select one option and see whether the listing updates without a full page reload. Then clear the selection or use a reset facet if one is present on the page.

Do not move on to complex rules until the simple test works. If the test range is empty, the issue is almost always in the data source, index, listing template, or shortcode, not in your "nice-looking" range setup.

Configuring Ranges, Labels, and Interface Types in Detail

Setting up Range List involves several choices that directly affect how visitors interact with it. You need to choose the data source, define the boundaries, write the labels, select an interface type, decide whether multiple selection is allowed, and determine whether unavailable options should remain visible. Those decisions should not be made at random. They should be based on the specific page where the filter will be used.

Data Source: Numeric Values Only

Data source determines where FacetWP gets the number it compares against your ranges. In WooCommerce, that may be the price. In a real estate catalog, it may be square footage or room count. In an equipment catalog, it may be power, weight, voltage, volume, or operating temperature. In ACF-powered content, it may be a field selected from an ACF field group.

If a post has no value in the selected field, it will not appear in the expected range. If the value looks numeric to a human but technically contains extra characters, the outcome may still be wrong. In a typical project, it is worth checking 5-10 real items from different parts of the catalog separately: a cheap and expensive product, a small and large property, a record with an empty field, and a record with a decimal value.

Ranges: How to Define Boundaries Without Traps

Ranges is the core setting. Each row becomes a separate selectable option. Every row has a label, a minimum boundary, and a maximum boundary. If Min is empty, FacetWP uses the previous row's Max. If the first row has an empty Min, the minimum is treated as zero. If the last row has an empty Max, the range is treated as open-ended upward.

That automatic behavior is convenient, but it requires attention. It helps you define a chain of ranges quickly without repeating boundaries, yet the upper and lower boundaries both include matching values. A value of 100 may match both "up to 100" and "100-200" if the ranges are defined that way. Sometimes that is intentional, for example if you want overlapping segments on purpose. But in most catalogs, visitors expect one price to belong to one group.

To avoid unexpected overlap, write the labels honestly. If the ranges are inclusive, labels like "up to 100" and "100-200" are better replaced with "up to 99" and "100-200" when working with whole numbers, or you should accept the overlap as part of the design and account for it clearly. Be even more careful with decimal values: "up to 50" and "50-80" may both include exactly 50. If that matters, define the boundaries with your data precision in mind.

Open-Ended Ranges

Open-ended ranges make the list easier to understand. The first range can start from zero without an explicit Min, and the last one can have no upper limit. This works well for price, area, weight, and age: visitors do not need to see an artificial maximum you do not really control.

But the final open-ended range needs a meaningful label. "Over 100" or "100 and above" is clearer than "100+." For a Russian-language audience, the wording may depend on the subject matter: "100 m2 and up," "100 kg and above," or "Over 5000 RUB," if a currency label makes sense in the visible text. The numeric field itself still remains unit-free.

Decimal Values

The Range List documentation confirms support for decimal numbers in range boundaries. That is useful for ratings, weight, area, volume, thickness, and other measurements. The format must stay technical: a period instead of a comma, with no spaces or thousands separators. For example, 3.5, not 3,5.

If users in your market are used to seeing a comma in labels, you can still use it in the visible range label, but not in the Min or Max field. In other words, the label may say "3.5-4.0 kg" using local formatting preferences, while the technical boundaries remain 3.5 and 4.0. That separation is completely fine: the label is for people, the boundaries are for comparison.

UI Type: Checkboxes, Radio, Dropdown, or fSelect

Range List can be displayed using several interface types. This matters more than it may seem: the same set of ranges is perceived differently in a store sidebar, above a product grid, inside a mobile filter panel, or in a long-form selection form.

For most store price ranges, it is best to start with Radio or Dropdown. Visitors usually choose one price segment, not several. The same applies to catalogs with groups like "up to 10 kg," "10-20 kg," and "20-50 kg." Checkboxes makes sense if the ranges overlap or if users genuinely need to combine several segments to broaden the result set.

Default Label and the "Any" Option

For Radio, Dropdown, and fSelect, a Default label setting is available. It defines the text for the "Any" selection. In a Russian-language interface, this does not have to be a literal equivalent of "Any." For price, you might use "Any price"; for area, "Any size"; for weight, "Any weight."

If Radio is used as a strict single-choice selector, leaving Default label empty can remove the "Any" option. But in most cases, it is better to keep a clear reset choice, otherwise users may not immediately understand how to return to the full list. If the page already includes a global reset facet, the issue is less critical, but a local reset option still improves usability.

Facet Logic and Multiple Selection

Facet logic appears for Checkboxes and for fSelect when Multi-select is enabled. OR (match any) broadens the result set: a record matches if it falls into at least one selected range. AND (match all) narrows the result set: a record must match several selected options at the same time.

For non-overlapping numeric ranges, AND is usually pointless, because one product cannot be both "up to 50" and "100-200" at the same time. For overlapping groups, it may make sense, but that is already a more advanced setup. In a typical catalog, use OR if you allow multiple selected ranges. If you only need one range, choose Radio or Dropdown and avoid unnecessary complexity.

How Range List Turns a Number Into a Visible Choice

Range List has some behind-the-scenes behavior that is worth understanding before you launch it on a live catalog. Visitors do not see the original numbers. They see the predefined options you created. But FacetWP still works through the index, technical values, and AJAX-based listing updates. Once you understand that chain, troubleshooting becomes much easier.

The Path From Record to Result

Everything starts with a numeric value stored on a post, product, or other object. For example, a product may have a price of 79, a property may have an area of 62, or a participant may have a birthdate from which age is calculated through a hook. When you create the facet and run Re-index, FacetWP analyzes the records and stores facet data in its index table. For Range List, the critical part is that the index can match each record's value to the ranges you defined.

After the page loads, FacetWP outputs placeholders for the facet and the results listing. FacetWP's JavaScript populates the facets and listens for visitor selections. When a visitor chooses a range, the selected value is stored in the FacetWP state and reflected in the URL parameters. FacetWP then sends an AJAX request, receives the updated results list, and refreshes the facets based on the current filtering conditions.

That behavior explains several common symptoms. If the facet does not appear at all, there is often no valid FacetWP-compatible listing or shortcode. If it appears but contains no options, the issue is more likely in the index, data source, or empty values. If the options appear but the outcome looks wrong, check the boundaries, the inclusive nature of Min/Max, range overlap, and selection behavior.

Why Re-Indexing Is Required After Changes

In FacetWP, the index is not a page cache. It is a working table used to calculate facet options and results efficiently. When you change ranges, the data source, the facet's internal name, a hook that affects indexing, or import content in bulk, the old index may no longer match the new rules. That is why you should click Re-index after those changes.

You do not need a full re-index after every edit to a single product if the automatic indexer is enabled and you are just saving a normal post update. But after creating a facet, changing its settings, importing content, modifying the structure of a custom content type, or adding code to facetwp_index_row, re-indexing becomes part of the setup process.

What "Ghost" Options Mean

Show ghosts controls how options behave when they would return no results after filtering. If the setting is off, those ranges disappear. If it is on, they remain visible but appear dimmed and cannot be clicked. This helps visitors understand that the group exists but is currently unavailable because of other selected filters.

There is a specific nuance for Range List: the documentation describes the ability to intentionally create ranges that already have zero results before any filtering, and with "ghost" options enabled, they can still remain visible. That can be useful if you want to display a full pricing or sizing structure even when some segments are currently empty. But in a standard store, those may look like dead options. The right choice depends on the UX goal: whether you want to show the full structure or hide anything that does not lead to results.

Practical Example: Price Ranges for a WooCommerce Catalog

Let us walk through a typical use case: a store wants to replace free-form price input with clear predefined groups. This example can easily be adapted to area, weight, or any other numeric parameter, but WooCommerce is especially convenient because price is a common data source and clearly shows the relationship between the catalog, the filter, and the results.

Goal

You want to place a filter with predefined price ranges next to the product archive. The visitor selects one group, the product list updates, the other facets recalculate, and the URL reflects the selected state. The administrator should also understand how to verify the outcome and what to do if some products disappear unexpectedly.

Preparation

Before configuring the facet, make sure your WooCommerce products are published, prices are filled in, and the product archive or custom listing is compatible with FacetWP. If you are using variable products, decide separately whether variation support should be enabled in FacetWP settings. FacetWP's WooCommerce documentation notes that enabling variation support requires a re-index. If variations are not used on that page, do not turn this setting on "just in case," because it increases the amount of indexed data.

Also check the out-of-stock product settings. WooCommerce and FacetWP may treat unavailable products differently: WooCommerce controls catalog visibility, while FacetWP does not index out-of-stock products by default. If you want those products to appear in the archive and the filters, the settings must be aligned, and then you need to run a re-index.

Setup Steps

1. Open Settings > FacetWP and create a new facet.
2. Select Range List as the facet type.
3. Enter a clear Label, such as "Price."
4. Keep the internal name short and in Latin characters, for example price_range.
5. Under Data source, choose the WooCommerce price source if it is available in your setup.
6. Add ranges such as "Up to 50," "50-100," "100-200," and "200 and above."
7. For the first range, leave Min empty and set Max to 50.
8. For the following rows, use the automatic chain or define the boundaries explicitly if you want tighter control over overlaps.
9. Choose a UI type: for single selection, start with Radio or Dropdown.
10. Save the facet and click Re-index.
11. Place the shortcode [facetwp facet="price_range"] next to a FacetWP-compatible product listing.

After these steps, do not rush into styling changes. Test the math first. Open a few products from different ranges, note their prices, and make sure they appear in the expected group. Then test both the lowest and highest range on the front end.

Verifying the Outcome

A proper check has three levels. The first is visual: the list of options is visible, the selected range is highlighted, and the results update. The second is logical: the products match the selected prices. The third is technical: the URL changes predictably, there are no JavaScript errors in the console, and other facets do not disappear for no reason.

If the page output does not match what you expect, do not rush to change all the ranges. Open one product with a known price and check whether it falls into the selected range, taking inclusive boundaries into account. Then run a re-index. If the problem remains, temporarily disable caching and JavaScript optimization so you can rule out stale front-end files.

The Boundary Overlap Nuance

With price ranges, it is important to decide how you want boundary values handled. If your ranges are "Up to 100" and "100-200," a product priced at 100 may fall into both because Range List uses inclusive comparisons. For many stores, that is undesirable. The right fix depends on price precision. With whole-number prices, you can use "Up to 99" and "100-199," then make the final range "200 and above." With decimal prices, choose boundaries that do not make the labels misleading.

Sometimes overlap is useful. For example, if you are showing not strict price brackets but marketing segments such as "budget," "mid-range," and "premium," some products may reasonably belong to two segments. But if that is the intent, it should be clearly understood by the site's editor and support team. Otherwise, someone will assume the filter is broken a month later.

Behavior Tuning: Overlaps, Ghost Options, and Counters

Once the basic filter is working, the next set of questions usually follows: should counters be shown, what should happen with empty groups, which logic should apply to multiple ranges, is it worth hiding result counts, and how should unavailable options be presented to users? These settings do not affect installation, but they do affect the quality of the user experience.

Overlapping Ranges as an Intentional Tool

Starting with the version where Range List explicitly allowed 0 and other numeric values in Min, it became possible to create overlapping ranges deliberately. That is not a bug. It is a supported feature. For example, you can define groups like "up to 50," "up to 100," and "100 and above," or "beginner," "intermediate," and "professional," where the boundaries are intentionally layered.

This approach is useful when the ranges reflect user intent rather than strict intervals. In a course catalog, a "beginner" level might include difficulty values from 0 to 3, while "confident users" might cover 3 to 6. A value of 3 sits on the boundary and may legitimately belong to both groups. That is less common in stores, but it can be practical in educational, service-based, and reference catalogs.

The key is not to mix overlapping ranges with ordinary strict intervals unless the project documents the reason. If the editor does not know the overlap is intentional, they may "fix" the boundaries and unintentionally change how the filter behaves.

When to Enable Show Ghosts

Show ghosts helps preserve the full selection map. Suppose a user first chooses the "Laptops" category and then selects the "up to 500" range. The "2000 and above" range may become unavailable. If it disappears, the interface becomes shorter, but the user no longer knows whether that option existed at all. If it remains dimmed, the interface communicates honestly: this group exists, but it does not return results under the current filter combination.

Enable ghost options when the catalog is complex and users benefit from seeing the full structure. Disable them if empty items clutter the page or if brevity matters more in a mobile filter panel. There is an extra nuance with fSelect in multi-select mode and OR logic: ghost options may not appear because of selections inside the facet itself, but they may appear because of other facets. So test the behavior on the real page, not just in the admin panel.

Counters: Show, Hide, or Adjust

Counters next to ranges help visitors estimate how many results they will get. But they are not always necessary. In a compact dropdown, counters can look noisy. In a price filter with four groups, they help communicate how full the catalog is. In a premium service catalog, they may be less useful because the number of results is not the main decision factor.

The Range List documentation shows several ways to hide or alter counters depending on the interface type. For Checkboxes and Radio, you can hide elements with the .facetwp-counter class, while dropdown-like interfaces use the facetwp_facet_dropdown_show_counts filter. Be careful, though: a generic CSS rule may hide counters in other facets too, so it is better to scope the rule to a specific facet or facet type.

Safe CSS to Hide Counters for One Facet

If you only need to remove counters from a single Range List facet using Checkboxes or Radio, start with CSS. Add it to a child theme, the theme's custom CSS area, or another safe snippet location that does not modify plugin files. Replace price_range with your own facet's internal name.

.facetwp-facet-price_range .facetwp-counter {
  display: none;
}

Testing is straightforward: open the page with the filter, confirm that the range labels remain visible, and make sure the numbers in parentheses disappear only for the intended facet. To roll it back, remove the rule or comment it out temporarily. If the counters do not disappear, check the actual facet name in the HTML class. FacetWP builds the class name from the facet's internal name.

When You Should Not Hide Counters

Do not hide counters just for aesthetics if users are choosing between closely related ranges. The numbers help them understand that "200 and above" has 2 results while "50-100" has 80. That can change how they browse. If the counters look unattractive, try adjusting the size, color, and spacing first instead of removing useful information.

Localizing Labels and Handling Unusual Numeric Setups

Range List is often used on sites where labels need to be not just technically correct, but editorially polished. A price may include a currency, an area value may need a unit, age may require natural wording, and on a multilingual site the same filtering behavior must be displayed properly in different languages. The important thing here is to separate three layers: the source number, the technical boundary, and the visible label.

Translating Range Labels

The official documentation describes label translation through the facetwp_facet_display_value hook and also mentions alternatives through facetwp_facet_html and facetwp_facet_render_args. In practice, that means you can adapt labels at render time without changing the mathematical boundaries themselves.

For a multilingual site, first check whether the appropriate FacetWP add-on is installed for WPML or Polylang, if you are using either of those systems. The Multilingual documentation specifically states that WPML and Polylang require the integration add-on, and that after configuring translations, it is important to re-index the data. If Range List uses ACF fields, those fields also need to be translated correctly or duplicated across each language version.

Do not translate the facet's internal name into Cyrillic. It is used in the URL and JavaScript state, so it should stay short and based on Latin characters. Translate only the visible label and the range labels.

Age Groups Based on Birthdate

One of the useful examples in the Range List documentation is age grouping. If you already have a numeric age field, the setup is simple: just use it as the data source. But if you store a birthdate instead, you first need to convert that value into age during indexing. The documentation suggests doing this with facetwp_index_row: when indexing runs, the date value is converted into a number of years and written into facet_value and facet_display_value.

This is useful for directories of professionals, participants, pets, athletes, candidates, or events with age restrictions. But it requires care: the date must be stored in the expected format, the code should only apply to the specific facet, and any code change should be followed by a re-index.

Below is an adapted version of the idea from the official documentation. It is not universal code for every site: replace age_range with your own facet name and verify the date format on a staging copy of the site.

add_filter( 'facetwp_index_row', function( $params, $class ) {
  if ( 'age_range' !== $params['facet_name'] ) {
    return $params;
  }

  if ( empty( $params['facet_value'] ) ) {
    return $params;
  }

  try {
    $birthdate = new DateTime( $params['facet_value'] );
    $now = new DateTime( 'now' );
    $age = $birthdate->diff( $now )->y;

    $params['facet_value'] = $age;
    $params['facet_display_value'] = $age;
  } catch ( Exception $e ) {
    return $params;
  }

  return $params;
}, 10, 2 );

After adding the snippet, run Re-index. Then open a record with a known birthdate, select an age range, and verify that the record appears in the results. To roll it back, disable the snippet and rebuild the index again to restore the original value.

Units in the Label

Do not store measurement units inside the numeric field. If an area field contains 75 m2, Range List does not receive a clean number. The correct approach is to store 75 and write the visible range label as "Up to 75 m2" or "75-120 m2." The same applies to weight, volume, power, and price.

If units may vary, for example between kilograms and pounds, do not mix them inside a single facet. Create a separate normalized field where all values are converted to one unit, then use that field as the data source. Otherwise, visitors may see clear labels while the numeric comparison remains mathematically wrong.

Placing the Filter on the Page and Combining It With Other Facets

Range List only becomes useful when it appears in the right place next to the right listing. By itself, the facet does not know which layout will be most convenient for visitors. That part is decided by the page author: a sidebar, a panel above the results, a mobile slide-out area, a short block inside the page, or a page builder integration.

Shortcode, Block, or Builder Widget

FacetWP supports displaying facets through shortcodes, PHP, and editor integrations. For Range List, that means the basic approach looks like this: [facetwp facet="price_range"]. In the WordPress Block Editor, you can place it in a Shortcode block, and if the appropriate add-ons are available, you can use FacetWP blocks or widgets. Elementor and Beaver Builder have their own facet output methods through integration add-ons.

The best method depends on where the results listing is built. If the catalog is created by a standard theme, a shortcode in the sidebar is often enough. If the page is built in Elementor, it is usually better to use the documented FacetWP widget when available, so you are not fighting the builder's internal behavior. If the listing is output through a PHP template, you can use facetwp_display() or do_shortcode() in a child theme.

Do not place the same facet multiple times on one page without a clear reason. Duplication can confuse visitors and make troubleshooting harder. If you need the filter in both a desktop sidebar and a mobile panel, check how the chosen theme hides and reveals blocks so FacetWP does not end up with two conflicting elements using the same facet name.

Combining It With Search, Sort, Reset, and User Selections

Range List rarely works alone. A page may also include search, categories, sorting, a reset button, and a selected-values block. In that combination, Range List handles the numeric grouping, Search handles the text query, Sort controls the order, Reset clears the state, and User Selections shows the active conditions.

For users, that feels like one unified filtering flow, but for troubleshooting it is important to separate responsibilities. If search works but Range List is empty, the problem is not the overall AJAX layer. If Range List filters correctly but reset does not clear the choice, inspect the reset facet settings. If selected values show a technical label instead of a readable one, check the facet label and translation setup.

A Practical Pairing With Mobile Flyout

On mobile screens, a range list can take up too much space. If the page contains several facets, a safe combination is to use Range List together with FacetWP's mobile panel, if that feature is available in your version and license. Range List keeps its role: numeric groups. The mobile panel serves a different purpose: opening the full filter set compactly without crowding the top of the page.

The setup order is simple: first make sure Range List works on a standard page. Then add the mobile panel and move the facet set into it. Verify that the facet label is clear, the ranges fit, the selection remains after closing the panel, reset clears the state, and the page does not scroll unexpectedly. If the facet disappears after enabling the mobile panel, temporarily switch back to the standard output and check whether the theme layout conflicts with the panel container.

Working With WooCommerce and ACF Without Making Unverified Assumptions

FacetWP documents built-in support for WooCommerce and Advanced Custom Fields. That does not mean every complex store or every field will work correctly without testing. In WooCommerce, key factors include variable products, price availability, out-of-stock product settings, and the archive type. In ACF, you need to choose the correct source under the ACF heading, confirm that the field is actually filled in, and understand the limitations of that specific field type.

A safe rollout path looks like this: first create one Range List facet on a clean numeric field, then add the remaining facets, then enable integration add-ons, mobile panels, caching, and optimization. If you turn everything on at once, it becomes much harder to isolate the cause when something breaks.

Performance, Indexing, and SEO for Filtered URLs

Range List is usually not the heaviest facet type, because the number of options is defined by the administrator. But it still runs inside the broader FacetWP system, and filtering speed depends on the index, the number of records, the complexity of the listing, the theme, other plugins, and the server. A solid rollout therefore includes not just a visibility check, but also a performance check.

Why Speed Depends on More Than FacetWP

FacetWP uses its index for fast comparisons, but updating the results still requires an AJAX request and rendering the listing. If each product card triggers many queries, the theme is heavy, the server is weak, and the page contains 20 facets, filtering will be slower. The official performance documentation explicitly points out that FacetWP can only be as fast as the site's raw queries and the results template allow.

For Range List, the takeaway is clear: do not create dozens of facets and massive pages just because one range list happens to perform well. Test the real page. If the listing is built with Listing Builder, it is often easier for FacetWP to handle than a complex theme archive, but the final outcome still depends on the specific project.

When to Use FacetWP Caching

FacetWP offers a separate Caching add-on that stores FacetWP AJAX requests for filter combinations in the database. That can help on high-traffic pages with repeated filter combinations. But caching does not fix poor data structure or a heavy template. First measure where the delay actually comes from: the index, the query, the product card rendering, third-party plugins, or JavaScript optimization.

If the site uses WP Rocket, FacetWP's documentation describes built-in support in newer FacetWP versions as well as separate recommendations for clearing caches after changing facets, Listing Builder, add-ons, or custom JavaScript. The practical conclusion is simple: after changing Range List, clear the page cache, the CSS/JS optimization cache, and any site-specific caches your setup uses. Then test the page in a private browsing window.

SEO: Should Filtered Combinations Be Indexed or Blocked?

Range List changes the URL to reflect the selected state. That is useful for visitors because a filtered catalog view can be saved or shared. But from an SEO perspective, that does not automatically mean every combination should be available to search engines. If you only have a few important ranges that produce useful landing states, they may be worth considering as part of a content strategy. If the combinations are numerous, they can dilute crawl efficiency and create thin pages.

Do not expect SEO growth just because a filter exists. A range filter improves navigation, but search value depends on content, demand, result uniqueness, and indexing rules. For large stores, it is worth planning canonical, noindex for unimportant combinations, the internal linking structure, and which filters should be exposed to crawlers. Those decisions go beyond Range List, but the facet itself participates in generating those URLs.

What to Test After Enabling Optimization

After turning on caching, minification, or deferred JavaScript loading, go through several actions as a regular visitor:

• Open the page without parameters and make sure Range List appears.
• Select one range and verify that the results update without a console error.
• Refresh the page with a range selected in the URL and confirm that the state is restored.
• Clear the selection using reset or the "Any" option.
• Check the mobile panel if filters are hidden on small screens.

If an error appears only after optimization is enabled, first disable deferred JavaScript loading for testing. Then follow the documentation for the specific caching plugin. Do not change the ranges until you have separated an interface issue from a data issue.

Troubleshooting Common Problems

Problems with Range List tend to look similar: the facet does not appear, the options are empty, the ranges return strange results, the counters do not match expectations, or filtering breaks after caching is enabled. Below is a practical troubleshooting flow that avoids panic and does not require editing plugin files.

The Facet Does Not Appear on the Page

Symptom: the shortcode has been inserted, but there is no range list on the front end, or only an empty container is visible. Possible causes include the add-on not being active, the internal name being typed incorrectly in the shortcode, the page not containing a FacetWP-compatible listing, JavaScript failing to populate the placeholder, or the theme outputting the block in the wrong place.

What to check: open Settings > FacetWP and make sure the facet exists, is set to Range List, and has been saved. Compare the name shown in the facet's gray field with the name inside the shortcode. Confirm that the same page also contains a results listing that FacetWP can filter.

How to fix it: temporarily place the facet and a test Listing Builder template on a simple page. If everything works there, the problem is in the original layout or query. If it still does not work there, go back to the add-on installation, the index, and the data source.

The Ranges Are Visible, but the Selection Does Not Change Anything

Symptom: the options are clickable, the URL or state changes, but the results list stays the same. The most common reason is that FacetWP is not controlling that specific listing, the page contains several conflicting listings, or the custom query is not connected to FacetWP.

What to check: temporarily switch to a standard supported listing or Listing Builder and test the same facet there. If filtering works on the standard listing, Range List itself is configured correctly and the issue is in the output template. If it fails everywhere, check the data source and the index.

How to fix it: convert the listing to a supported type, use the documented builder integration, or correct your custom WP_Query according to the FacetWP documentation. Do not add a second results listing to the same page as a quick workaround, because that only makes the filter state harder to manage.

The Range Options Are Empty or Disappeared After Settings Changed

Symptom: the facet appears, but there are no options even though matching records exist. Possible causes include not running Re-index, the field not being numeric, empty values, the wrong ACF source being selected, the custom post type not being indexed, or content being imported without re-indexing afterward.

What to check: run a re-index, then inspect a few records with real values. For ACF, make sure the source is selected under the ACF heading. For a custom post type, verify that it is searchable and not excluded from search at the registration level.

How to fix it: normalize the values, save a few test records, and rebuild the index. If the custom type is not indexed, fix its registration or the settings of the plugin that creates it. After changing the structure, run Re-index again.

A Product or Post Falls Into the Wrong Range

Symptom: an item with a known price, area, or weight appears in an unexpected group. Most often, the cause is inclusive Min and Max boundaries, overlapping ranges, decimal values, or a difference between the displayed price and the indexed price.

What to check: open the value in the admin panel, compare it with the technical boundaries, and remember that both edges are inclusive. For WooCommerce, verify which field is selected as the source: price, sale price, regular price, or another source. For variable products, check the variation support settings.

How to fix it: refine the boundaries and labels. If overlap is not intended, separate the edges. If the front-end price differs because of discounts or variations, choose the correct source and re-index.

Ghost Options Behave Differently Than Expected

Symptom: some ranges disappear, become dimmed, or stay visible with zero results. This is tied to the Show ghosts setting, the facet behavior, and the effect of other selected facets.

What to check: temporarily turn Show ghosts on and off, repeat the same actions on the page, and observe how the options change. For fSelect with Multi-select, also check Facet logic, because OR and AND behave differently.

How to fix it: choose the behavior based on UX goals. If visitors need a full map of the available groups, keep ghost options enabled. If the page feels cluttered and empty groups do not help, disable them. Do not use ghost options as a substitute for a well-designed range structure.

The Filter Stops Updating After Caching or Optimization Is Enabled

Symptom: Range List worked during testing, but after enabling caching, minification, or deferred JavaScript loading, the selection no longer updates the listing or console errors appear. The cause is usually not the range boundaries, but script loading or stale cached assets.

What to check: clear the page cache, CSS/JS cache, and optimizer cache. Open the page in a private window. Temporarily disable the problematic JavaScript optimization. If you use WP Rocket, compare your setup against FacetWP's current recommendations for that combination.

How to fix it: configure exclusions or update the integration based on the documentation. After changing FacetWP or add-on settings, always clear the relevant caches. If the problem disappears when optimization is disabled, do not change Range List until the caching plugin is configured correctly.

The Index Is Empty or Takes Too Long to Build

Symptom: after Re-index, you see a message about an empty table, the process takes too long, or some records never make it into the index. Possible causes include non-indexable post types, empty values, a multilingual site missing the required add-on, a very large number of products and variations, or heavy custom hooks.

What to check: use FacetWP's indexing tools to inspect which post types are being indexed. Estimate the number of products, variations, facets, and values involved. If code was recently added to facetwp_index_row, temporarily disable it on a staging copy and compare the indexing speed.

How to fix it: limit indexing to the required content types, disable variation support if you do not need it, normalize the fields, review multilingual settings, and run the index again. If the database is large, schedule indexing for a quiet period and avoid running several heavy processes at once.

Limitations and Decisions Worth Making Up Front

FacetWP Range List looks simple, but it touches data, interface behavior, indexing, and URL behavior. Because of that, several decisions are best made before launch: how many ranges should appear on the page, what they should be called, whether multiple selection is allowed, how to handle zero-result groups, which combinations with other facets are acceptable, and who will maintain the values after launch.

Do Not Turn Range List Into a Long Reference List

If you end up with 30 ranges, you may be using the wrong tool. A long list of predefined intervals is worse than a slider or numeric input. Visitors start scrolling through the filter instead of choosing from it. A good Range List usually contains a handful of meaningful groups. If the number of groups is high because your catalog is complex, split the task: one facet for category, another for range, and a third for availability or another key attribute.

Do Not Treat a Text Field as a Number

On older WordPress sites, meta fields are often filled in inconsistently. Today an editor enters 100, tomorrow 100 USD, and the next day about 100. To a visitor, those may look similar, but to Range List they are different values. If a field is supposed to be filtered numerically, define a formatting rule and include it in the instructions for your content editors.

Do Not Promise Full Compatibility Without Testing

FacetWP has many integrations, but a real site may be using a theme, page builder, caching, imports, multilingual plugins, and WooCommerce extensions all at once. In that environment, Range List is best introduced gradually. Start with a staging copy, then one facet, then the main listing, then the remaining facets, then caching and the mobile panel. If something breaks, you will know exactly at which step it happened.

Document the Boundaries You Chose

A few months from now, no one will remember why the range labeled "up to 100" technically ends at 99, while the "100-200" range begins at 100. Document the reasoning next to the project settings: which unit is used, why the boundaries were chosen that way, whether the groups overlap, and what should happen when new products are added. This matters especially on sites where editors regularly import new data.

When FacetWP Range List Is the Right Choice

FacetWP Range List is a strong choice when the site already has a FacetWP-compatible listing and clean numeric data, and when visitors are better served by selecting predefined groups than by dragging a slider or typing values manually. It works especially well for price, area, weight, age, rating, and other parameters where the editor can define clear boundaries in advance.

Before launch, verify four things: the data source is truly numeric, the ranges are labeled honestly, Re-index has been run after any settings changes, and the filter has been tested on the front end together with caching and other facets. If those conditions are met, Range List provides a clean and predictable selection interface.

When you are ready to repeat the setup on your own site, you can download the installation file and test it first on a page copy or a staging catalog. That approach is safer than changing a live archive immediately, because you can see how the ranges, index, URL, and neighboring facets behave against your actual data.