This is a guide on how to upgrade from version 2 to version 3.

Upgrading from version 2 to version 3 is currently a manual process, automatic updates are not enabled for this update.

We are creating a migration tool to help automate this process which will be ready around December 2024.

Checkout the video for an in depth look at how to migrate your site today or take a look below for an overview of the main changes.

Splitting Search Forms

A version 2 search form typically comprises of a Settings & Defaults section where you can configure your query and a Search Form section for building your search form layout.

Version 3 splits a traditional search form into 2 distinct parts:

• Settings & Defaults are now known as Queries
• Fields are now split out into their own section and can be reassigned to any Query you have created.
• Fields can now be placed individually, anywhere on page, rather than together as a predefined search form.

Queries

Version 3 queries still have many similarities to the Settings & Defaults section in version 2.

One of the key differences is that the display results tab has been moved to the front and is now called integration.

Instead of defining your query settings first, you first choose how to integrate.

Integration methods

One of the biggest changes is the way we setup queries and integrate them in your site. Let’s cover the main differences with each display method.

Post type archive + taxonomy archive

Choosing the post type archive display method allows you to perform searches on your frontend post type archives.

The new way to configure this is to choose your archive type from within the integration tab, and then your post type.

New to version 3 is support for filtering only on specific taxonomy archives.

Results shortcode

To support displaying the results as a shortcode we need to first enable the option in the settings screen, then click the configure icon:

From the popup, enable the results shortcodes option:

Then enable it in the query settings:

Using the shortcode

Search & Filter shortcodes have changes since version 2, displaying the results should now use the format:

[[searchandfilter query="1" action="show-results"]]

Note: the container CSS class has changed to .search-filter-query--id-1 from .search-filter-results-1

* The above examples all use 1 as the query ID, be sure to replace this with your actual query ID.

As an archive (deprecated)

Version 2’s “as an archive” method is no longer available in version 3. The reason being is that it was bad for SEO, and hard to update the page title.

While it allowed you to use custom templates for displaying results in a similar format to post type archives, these archives were never recognised as “true” WordPress archives which meant that SEO plugins also didn’t know what to do with them.

The main advantage of this display method was that you could design your page & results in PHP.

If it is required to build the entire page in PHP, this can be also already be done in WordPress using custom page templates and combining that with our results shortcode to have full control over the page layout.

Integrations

Version 3 supports some of the integrations that were possible in version 2 but not all of them, just yet. We’re working on filling in the missing integrations over the coming months.

Available today

• Advanced Custom Fields (ACF)
• WooCommerce
• Elementor
• Beaver Builder

Currently working on

• Dynamic Content for Elementor
• Divi
• WP Bakery Page Builder
• Relevanssi
• Easy Digital Downloads

New integrations planned

• Bricks Builder

Fields

Fields are a lot more flexible in version 3. There are more configuration options, new design options, and you can now move fields from one query to another.

You can create a field first, then assign it to a query, or add a new field directly to an existing query.

Once you’ve chosen to create a field, you will find the new field editor.

Fields can be added using shortcodes (found underneath the field editor) or by using blocks.

Our plan for upgrading

• We’ll create a migration tool to convert existing v2 search forms into v3 fields and queries.
• After the migration you will need to relink / replace the search forms on the frontend with the new fields
• For heavily customised implementations, we’ll release a developer guide on how to migrate – this will be a manual process and will require some development time.