JPKCom DB
View on GitHub

JPKCom Post Filter — Guide & Tips

Faceted taxonomy filtering for posts, pages and custom post types with JPKCom Post Filter — SEO-friendly URLs, AJAX, shortcodes, blocks and page builder support.

JPKCom Post Filter adds faceted taxonomy filtering to any WordPress archive page — for posts, pages and any custom post type. Every filter state is encoded in an SEO-friendly URL like /blog/filter/web-design+marketing/wordpress/, so it is shareable and bookmarkable; filtering runs via AJAX with a full no-JavaScript fallback.

Guide

Requirements

  • WordPress 6.9 or newer (tested up to 7.0)
  • PHP 8.3 or newer
  • No dependencies: no ACF, no Bootstrap, no jQuery required

Page builder support is optional — the Gutenberg blocks, Elementor widgets and Oxygen elements load only when the respective builder is active.

Installation

  1. Upload the jpkcom-post-filter directory to /wp-content/plugins/ (or install the ZIP via Plugins → Add New → Upload Plugin).
  2. Activate the plugin under Plugins → Installed Plugins.
  3. Under Post Filter → General, select the post types to filter.
  4. Under Post Filter → Filter Groups, add the taxonomies you want as filter dimensions.
  5. Go to Settings → Permalinks and click Save Changes to flush the rewrite rules.

Configuring filter groups

Each filter group maps a taxonomy to a URL position; the group order determines the order of the URL segments. Per group you set the taxonomy, label, target post types, a numeric sort position (Order) and an on/off toggle (Enabled).

You can register new taxonomies right from the Filter Groups page (the "Register as new WordPress taxonomy" option): slug, rewrite slug, hierarchical/flat, public, admin column and REST API visibility (required for Gutenberg) are all configurable.

Warning: Deleting a filter group that registered a custom taxonomy unregisters that taxonomy — all term assignments on posts are permanently lost.

Output: auto-inject, shortcodes, blocks

There are three ways to render the filter and list:

  • Auto-inject (General → Auto-Inject Filter): the plugin automatically wraps the theme's archive loop with the filter UI — no shortcode or template edit needed. It hooks into loop_start/loop_end on archive/blog pages (not on singular posts, search or pages).
  • Shortcodes: [jpkcom_postfilter_filter], [jpkcom_postfilter_list] and [jpkcom_postfilter_pagination]. The interactive shortcode builder under Post Filter → Shortcodes generates ready-made snippets.
  • Builders: three Gutenberg blocks, three Elementor widgets and three Oxygen elements each (Post Filter, Post List, Post Pagination).
[jpkcom_postfilter_filter post_type="portfolio" layout="dropdown"]
[jpkcom_postfilter_list post_type="portfolio" layout="cards" limit="12"]
[jpkcom_postfilter_pagination post_type="portfolio"]

Important: Shortcodes (and blocks/widgets/elements) always attach to the archive of the configured post type. They only work on an archive template page or on the page set as the "Posts Page" under Settings → Reading. On an arbitrary page (e.g. /test/) filter clicks and AJAX jump back to the archive URL — use auto-inject there instead.

Layout & design

Post Filter → Layout & Design offers six tabs (Global, Filter, Posts, Pagination, Color Schemes, Advanced). You choose from four filter layouts (bar, columns, sidebar, dropdown), three list layouts (cards, rows, minimal) and four color schemes (Default, Dark, Contrast, Monochrome). The Advanced tab controls the stylesheet mode (Full / Variables only / Disabled), the Plus/Minus mode, reset button visibility and your own custom CSS, among others.

Tips & Tricks

  • Change the URL endpoint: By default the filter sits under /filter/. Change the path segment under General → URL Endpoint and then click Flush Rewrite Rules (or re-save your permalinks).
  • Behaviour without filter terms: Use Bare Endpoint Behaviour to set what happens when /filter/ is accessed without terms — 404, redirect to the blog homepage, or a custom URL.
  • Multiple filter instances per page: Each filter/list/pagination set is paired via the post_type attribute (data-jpkpf-post-type), so different post types can be filtered independently on one page.
  • Four cache layers: Object cache, transients, APCu and a PHP settings file cache keep output fast. Caches are invalidated automatically on save_post/deleted_post or term changes; clear them manually under Post Filter → Cache.
  • Override CSS cleanly: All styles use CSS custom properties prefixed --jpkpf-. Set them in your theme stylesheet, in the variable fields under Layout & Design, or via the custom CSS field. For full control, set the stylesheet mode to "Disabled".
  • Override templates per theme: The loader checks child theme → parent theme → mu-plugins/jpkcom-post-filter-overrides/templates/ → plugin templates/. For example, copy templates/partials/list/list-cards.php to themes/your-theme/jpkcom-post-filter/partials/list/list-cards.php.
  • Migrate settings: Under Post Filter → Import / Export you can export all settings (general, layout, cache, filter_groups) as JSON and re-import them on another environment.
  • Constants in wp-config.php: among others, JPKCOM_POSTFILTER_URL_ENDPOINT, JPKCOM_POSTFILTER_CACHE_ENABLED, JPKCOM_POSTFILTER_DEBUG and JPKCOM_POSTFILTER_MAX_FILTER_COMBOS are overridable.
  • Build Gutenberg blocks from source: The block editor scripts need a build step (npm install && npm run build, output to blocks/build/). If the build directory is missing, the plugin skips block registration.
  • Accessible & SEO-ready: Filter terms are real <a> links (page reload without JS), the results zone uses aria-live, toggle buttons use aria-pressed. Each filter combination has a crawlable URL with a canonical set against duplicate content.

Further reading