Dependent Filters

A WordPress plugin for symmetric dependent filters (also called faceted dropdowns).

It keeps the options of existing selects available only when at least one matching post exists. It is independent of Themeco and CS Forms: it only requires standard HTML select elements.

What it does

• Queries a configured custom post type and post status.
• Works with any number of configured taxonomies.
• Recalculates every filter when a selection changes.
• For each dropdown, ignores its own current value while calculating valid options.
• Uses WordPress term IDs (term_id) as option values.
• Disables unavailable options by default; hiding them is also supported.
• Keeps the original form markup and option order intact.
• Does not modify the Looper, search results, URLs, WordPress content, or database.
• Dispatches a dependentFiltersUpdated browser event after every successful update.

Installation

1. Download the repository as a ZIP from GitHub.
2. In WordPress, go to Plugins → Add New → Upload Plugin.
3. Upload the ZIP and activate Dependent Filters.
4. Configure the plugin as described below.

Configuration

Edit config.php. This is the only project-specific file.

return [
    'post_type' => 'private-post',
    'post_status' => 'publish',
    'access' => 'public', // public | logged_in
    'load_on_pages' => [], // page IDs or slugs; [] loads everywhere
    'form_selector' => '#dependent-filters-form',
    'mode' => 'disable', // disable | hide
    'debug' => true,
    'debounce_ms' => 250,
    'disable_selected_style' => true,
    'filters' => [
        'type-content' => [
            'selector' => '[name="type-content"]',
        ],
        'raw-material' => [
            'selector' => '[name="raw-material"]',
        ],
        'industry' => [
            'selector' => '[name="industry"]',
        ],
        'country' => [
            'selector' => '[name="country"]',
        ],
    ],
];

Access

Set access to public for public content, including standard WordPress posts. The REST request still includes the normal WordPress nonce.

Use logged_in when the configured data should only be available to authenticated visitors. In that mode, a visitor without an active WordPress session receives no REST response; it is not a role or capability restriction, so every logged-in user can use the filters.

Asset loading

WordPress cannot inspect a browser-only CSS selector before it decides whether to load assets. To load the plugin only where the form exists, set the WordPress page ID or slug:

'load_on_pages' => [ 123 ],

or:

'load_on_pages' => [ 'my-search-page' ],

Leave the array empty to load on all pages. When access is logged_in, the CSS and JavaScript are not loaded for anonymous visitors.

Requirements for the form

• The form must match form_selector (the default expects id="dependent-filters-form").
• Every configured field must be a select inside that form.
• Each filter selector must identify its select uniquely.
• The value of each taxonomy option must be the WordPress term ID.
• The “All” option must have an empty value: All.

The taxonomy names in filters must be the actual WordPress taxonomy slugs. The plugin checks that the post type and taxonomies exist and are associated; configuration errors appear as an administrator notice.

CS Forms integration

In CS Forms, the AJAX change selector must target only the container of the results that need rebuilding. Do not include the form or its selects in that selector.

If CS Forms replaces the selects after an AJAX response, it removes the disabled or hidden state that Dependent Filters has just applied.

First test

1. Keep debug set to true.
2. Open the page containing the form.
3. Open the browser developer console.
4. Change any filter.

Expected result:

• The console displays messages prefixed with [Dependent Filters].
• The browser sends a POST request to /wp-json/dependent-filters/v1/options.
• The response contains available term IDs for every configured taxonomy.
• In disable mode, incompatible options become disabled and receive the df-disabled class.
• In hide mode, incompatible options are hidden.
• A dependentFiltersUpdated event is fired.

To inspect the event during testing, run this in the browser console:

document.addEventListener('dependentFiltersUpdated', console.log);

Set debug to false after testing.

How the calculation works

With these selections:

• Country: Uganda
• Industry: Energy
• Raw material: Lithium

the plugin calculates available options as follows:

• Country: posts matching Industry + Raw material
• Industry: posts matching Country + Raw material
• Raw material: posts matching Country + Industry
• Type content: posts matching Country + Industry + Raw material

This prevents users from selecting a combination with no matching posts.

Notes

The plugin loads no external JavaScript libraries and does not use jQuery.