Description
Ajax Filter Search is a small but powerful plugin that displays your posts or custom post type in a list or grid with category tabs, search, month and year filters and pagination, all using ajax so there’s no page reload.
A visitor can filter your posts by search keyword, month, year and category to get the exact content they’re looking for. It’s a great tool for anyone looking to show a reel of press releases, blog posts, upcoming events, whatever you can think of.
Features
- Gutenberg block and shortcode – Add the “Ajax Filter Search” block, or use the
[ajax_filter_search]shortcode anywhere. - Multiple feeds per page – Every feed has its own post type, categories, layout and filters.
- Shareable links – The first feed on a page keeps its filters and page number in the address bar, so a filtered view can be bookmarked or shared, and the back button works. It also works with JavaScript turned off.
- Fast, light front end – Plain JavaScript (no jQuery), a small stylesheet, and assets that load only on pages that contain a feed. No external fonts or icon libraries.
- Modern and Classic designs – A clean, card-based Modern design for new installs and the original Classic look for sites that already use the plugin. Choose one site wide or per feed.
- Sort and filter chips (optional) – Let visitors sort by newest, oldest, A to Z, recently updated or most commented, and show the active filters as removable chips with a Clear all link. Both are off until you turn them on.
- RSS feed for any view – Every filter state has its own RSS 2.0 feed at
/wp-json/afs/v1/feed, built from the same query as the results and listing published posts only. - Accessible – Labeled form fields, keyboard friendly tabs and buttons, live-region updates and a current-page indicator.
- Easy to theme – Set your accent color in Settings, or override any
--afs-*CSS variable. Developers can override the item template and use filters. - Settings panel – Choose the default post type, taxonomy, posts per page, layout and more under Settings > Ajax Filter Search.
Example shortcodes
[ajax_filter_search]
[ajax_filter_search terms="news,press-releases" posts_per_page="12" layout="grid"]
[ajax_filter_search post_type="event" post_tax="event_type" orderby="title" order="ASC" show_views="false"]
Shortcode attributes
All attributes are optional. Anything you leave out uses the setting from Settings > Ajax Filter Search.
post_type– post type slug.post_tax– taxonomy slug used for the category tabs (ornone).terms– comma separated term slugs to limit the feed to. (filter_byandfilter_typeare accepted as older names for the same thing.)posts_per_page– 1 to 100.layout–listorgrid, the layout the feed starts in.orderby–date,titleormodified.order–DESCorASC.search– a keyword to start with.filter_years/filter_months– start on a year (for example 2025) or month (1 to 12).show_tabs,show_views,show_search,show_months,show_years–trueorfalse.design–modernorclassic. Overrides the Appearance setting for this feed.show_sort,show_chips–trueorfalse. The sort control and the active filter chips are off unless you turn them on here, in the block, or under Settings.
Please Rate Ajax Filter Search!
Your ratings make a big difference! If you like and use Ajax Filter Search, please consider taking the time to rate the plugin. Your ratings and reviews will help this plugin grow and provide the motivation needed to keep pushing it forward.
Installation
Using The WordPress Dashboard
- Navigate to ‘Add New’ in the plugins dashboard
- Search for ‘Ajax Filter Search’
- Click ‘Install Now’
- Activate the plugin on the Plugin dashboard
Uploading in WordPress Dashboard
- Navigate to ‘Add New’ in the plugins dashboard
- Navigate to the ‘Upload’ area
- Select
ajax-filter-search.zipfrom your computer - Click ‘Install Now’
- Activate the plugin in the Plugin dashboard
Using FTP
- Download
ajax-filter-search.zip - Extract the
ajax-filter-searchdirectory to your computer - Upload the
ajax-filter-searchdirectory to the/wp-content/plugins/directory - Activate the plugin in the Plugin dashboard
FAQ
What are the steps to getting Ajax Filter Search to display on my website?
- Add the “Ajax Filter Search” block, or copy the shortcode
[ajax_filter_search], into your page. - Optionally adjust the defaults under Settings > Ajax Filter Search.
- View the page and watch Ajax Filter Search fetch your posts.
Is it possible to only display posts from 1 or 2 categories?
Yes. Add the terms attribute with the term slugs you want, separated by commas, for example [ajax_filter_search terms="news,events"]. Make sure the slugs belong to the taxonomy selected for that post type. (If you used filter_by with an older version, it still works.)
Can visitors sort the results or see which filters are active?
Yes, both are optional. Add show_sort="true" for a sort control and show_chips="true" for removable filter chips with a Clear all link (they also offer a way out when nothing matches). You can also use the matching block controls, or turn them on for every feed under Settings > Ajax Filter Search. They are off by default, so existing feeds look exactly as before.
Is there an RSS feed for a filtered view?
Yes. /wp-json/afs/v1/feed accepts the same parameters as the results endpoint (for example afs_term=news&afs_year=2025) and returns RSS 2.0 with published posts only. Developers can build the address with afs_feed_url() or remove the feed with add_filter( 'afs_enable_feed', '__return_false' );.
Will search engines index every filtered view?
No. A page that shows a feed and is opened with a filter, search or page number in the address is marked noindex, follow, so only the main page is indexed. You can turn this off under Settings > Ajax Filter Search or with the afs_noindex_filtered_states filter.
Is the ajax functionality secure?
The filters call a read-only REST endpoint (/wp-json/afs/v1/results) that only ever returns published content of public post types. All incoming values are validated and sanitized on the server, and the endpoint cannot change anything on your site, so no nonce is needed.
I’m upgrading from 1.x. What changes?
Version 2.0.0 is a major update. Please back up your site and try it on a staging copy first. The feed has new markup and a small new stylesheet, so custom CSS written for the old Bootstrap-based markup needs updating, and the Font Awesome icon font is no longer loaded. Theme template overrides keep working. A compatibility layer keeps the 1.x functions, constants, the first feed’s element IDs, the old script handles and the old ajax action working for now; it is deprecated and can be switched off with add_filter( 'afs_enable_legacy_compat', '__return_false' );. The filter_by attribute now limits a feed to category slugs, as the 1.x readme described; use search for a starting keyword. A short migration guide is in the plugin’s GitHub repository (docs/MIGRATION-1.x-to-2.0.md).
Can I change how each result looks?
Yes. Copy afs-template/default.php from the plugin folder into your-theme/afs-template/default.php (a child theme is checked first) and edit it. Templates written for version 1.x keep working. You can also use the afs_query_args and afs_template_file filters.
Does it load anything from third-party servers?
No. Version 1.x loaded Font Awesome from a CDN on every page. Version 2.0.0 loads nothing external.
Can I keep the old look?
Yes. The Classic design is the look of earlier versions, and sites that already use the plugin keep it. New installs start with the Modern design. Change it under Settings > Ajax Filter Search > Appearance, or for one feed with design="classic" or design="modern" (the block has a Design setting too).
How do I change the colors?
Pick the accent color under Settings > Ajax Filter Search. For more control, set CSS variables in your theme, for example .afs { --afs-accent: #0a7; --afs-radius: 0; }.
What happens to my data if I uninstall?
The plugin’s single settings option is removed when you delete the plugin. Your posts are never touched.
Screenshots










Changelog
2.2.0
- New: Modern design with card-based results, pill tabs, a cleaner filter bar and a segmented layout switch. New installs get it by default. Sites that already use the plugin keep the Classic look until they choose Modern (Settings > Appearance,
design="modern"on a feed, or the block’s Design setting). - New: Redesigned settings screen with section navigation, a design picker, copyable example shortcodes and a sticky save bar.
- Improved: Text on the accent color is now white or dark depending on the color you choose, so buttons stay readable with any accent, in both designs.
- Fix: Submitting a search no longer sends a second, delayed request that could undo a click on a tab or page link made right afterwards.
2.1.0
- New: Optional sort control (newest, oldest, A to Z, recently updated, most commented). Turn it on with
show_sort="true", the block control or Settings. - New: Optional active filter chips with Clear all, and a “Clear all filters” link when nothing matches (
show_chips="true", the block control or Settings). - New: RSS 2.0 feed for any filter state at
/wp-json/afs/v1/feed. It uses the same query as the results and lists published posts only. - New: The results endpoint returns a
metablock and, for logged-out visitors, sends cache validators so a repeat request is answered with an empty 304. - New: Filtered views of a feed page are marked noindex, follow so only the main page is indexed (setting, on by default).
- New: A dismissible notice for administrators when the theme has template overrides or styles written for 1.x, with a link to the migration guide.
- New: Extension points for add-ons: registries, the
afs_registeraction,afs_rest_response,afs_cache_version,afs_feed_url()and JavaScript hooks and events (afs:loaded,afs:results,afs:error). - Improved: The Update button is hidden when JavaScript is active. It stays for visitors without JavaScript.
- Improved: If an update request fails, the first feed on a page falls back to a normal page load and any other feed shows a Try again button.
- Improved: The category tab list is cached.
- Fix: In the block editor, clicking the preview no longer sends the editor canvas to a raw REST address; the preview is inert and a click selects the block.
- Security: Only published content can be listed, even if a site’s
afs_query_argsfilter tries to widen the post status.
2.0.0
- New: Gutenberg block with editor controls and live preview.
- New: Multiple feeds on one page, each with its own settings.
- New: Shareable, bookmarkable filter state in the address bar for the first feed on a page; works without JavaScript; back button supported.
- New: Shortcode attributes
terms,layout,orderby,order,search,show_tabs,show_views,show_search,show_months,show_years.filter_bynow does what the old documentation said (limit to category slugs). - New: Accent color setting and
--afs-*CSS variables. - New: Settings for the default layout;
afs_query_argsandafs_template_filefilters. - Security: Replaced the old admin-ajax handler with a validated read-only REST endpoint, escaped all output, and validate all settings on save. Includes every fix from 1.0.4.
- Improved: Front end rewritten in plain JavaScript (jQuery no longer required) with a small, scoped stylesheet. Assets load only on pages that use the plugin.
- Improved: Accessibility – labeled fields, ARIA states, keyboard friendly controls, announced updates.
- Improved: Fully translatable; dates and month names follow the site language and settings.
- Improved: Works with PHP 7.4 to 8.4 and WordPress 6.0 to 7.1; removed all PHP warnings from earlier versions (for example when two feeds shared a page).
- Improved: Child themes are checked for template overrides; the settings page and its scripts only load on the plugin’s own screen.
- Added: A deprecated compatibility layer for 1.x code: the 1.x functions, classes and constants, the old ajax action (now served by the same validated code), the first feed’s 1.x element IDs, the old script and style handles, and the
ajaxurl/scriptpathglobals on feed pages. Switch it off with theafs_enable_legacy_compatfilter. - Removed: The Font Awesome CDN, the bundled Bootstrap-derived CSS, SCSS sources and development junk from the plugin package.
- Added:
uninstall.phpremoves the plugin’s setting on deletion.
1.0.4
- Security: Hardened the ajax request handler. All submitted values are now validated.
- Security: Draft, scheduled and pending posts are no longer included in ajax results.
- Security: The settings-screen taxonomy lookup is now limited to administrators.
- Fix: Filtering no longer causes a fatal error on PHP 8.
1.0.3
- Function / Structure Improvements
- Bug fixes to address Page loop error.
- Added a template capability to the loop to allow for customization in the future.
- Added “filter_by” attribute to the shortcode to allow for selected categories in the loop
- Began ground work for color selection options in settings page
1.0.2
- Update to test Version #
1.0.1
- CSS Edits, A Few Bug Fixes, Added Screenshots, Robots text edits, Compiled SCSS files
1.0.0
- Ajax Filter Search
