Relevanssi Live Ajax Search

Relevanssi Live Ajax Search is a plugin that adds a live search. The plugin is easy to use: install and activate, and you’re ready! The plugin can take over most search forms automatically.

Relevanssi Live Ajax Search does not require Relevanssi: it works with the default WP search. Of course, it’s better with Relevanssi, and it’s compatible with Relevanssi, Relevanssi Premium, and Relevanssi Light.

Relevanssi Live Ajax Search is free and does not require a Relevanssi Premium license.

Relevanssi Live Ajax Search is available at the WordPress.org plugin repository.

Installing Relevanssi Live Ajax Search

Most of the time, installing Relevanssi Live Ajax Search is very easy. All you need to do is to install the plugin and activate it. Live Ajax Search is able to take over most search forms automatically.

Sometimes Live Ajax Search cannot hijack the search form without help. Especially if you are adding the search form manually on your site, you need to add the Live Ajax Search parameters to the search form. Add these parameters to the search term input field (the one with the name “s“):

data-rlvlive="true" to enable Live Ajax Search.
data-rlvconfig="default" to use the default configuration (if you have custom configurations, name the configuration here).
data-rlvparentel="#rlvlive" where #rlvlive is the id for the element that has the results. This parameter is optional and if you add this, you also need to add the element (an empty div) where you want the results to appear; inside the form tag is often good for accessibility.

A basic search form looks something like this:

<form role="search" method="get" class="search-form" action="/">
	<label>
		<span class="screen-reader-text">Search for:</span>
		<input type="search" class="search-field" placeholder="Search …" name="s">
	</label>
	<input type="submit" class="search-submit" value="Search">
</form>

With Live Ajax Search, the form should look like this:

<form role="search" method="get" class="search-form" action="/">
	<label>
		<span class="screen-reader-text">Search for:</span>
		<input type="search" class="search-field" placeholder="Search …" name="s"
          data-rlvlive="true" data-rlvparentel="#rlvlive" data-rlvconfig="default">
	</label>
	<input type="submit" class="search-submit" value="Search">
    <div id="rlvlive"></div>
</form>

Search results templates

The Live Ajax Search plugin uses templates to display the search results. Using templates means it is easy to override the default search results from your theme if you want to change the results.

You can find the default template Relevanssi Live Ajax Search uses in the templates directory of the plugin. You can copy the template to your theme: create a directory relevanssi-live-ajax-search in your theme directory and copy the file there. Now, Live Ajax Search will use this file to display the results, and you can modify the file as much as you want.

There are two templates in the templates directory. The default template is search-results.php. This template works just like any other WordPress template and uses the global $wp_query. There’s also search-results-query.php, which is used for the alternate query mode that is more compatible with third parties. This template uses a custom query object, $relevanssi_query.

Overriding the default styles

Live Ajax Search adds two sets of styles to your site. The first set is the baseline CSS that determines the position of the search results. To remove these styles, use this filter hook:

add_filter( 'relevanssi_live_search_base_styles', '__return_false' );

The second set covers more, and the plugin enqueues it as relevanssi-live-search. To disable these styles, dequeue that:

add_action(
  'wp_enqueue_scripts', 
  function() {
    wp_dequeue_style( 'relevanssi-live-search' );
  },
  99
);

Adjusting the spinner colour

Version 2.0 introduced a CSS spinner. To change the colour of the spinner, add this to your theme styles:

.rlv-has-spinner {
	border-color: #19892c;
	border-right-color: transparent;
}

.rlv-has-spinner::after {
	background-color: #19892c;
}

Filter hooks

relevanssi_live_search_add_result_div (boolean)
If this filter hook returns true, the plugin adds a specific div element for the results inside the search form and adds the results there. If this hook returns false, no extra element is added, and if nothing else is specified in the configs, the result element is appended at the end of the body. The default is true, because that makes it possible to move with a tab from the form to the results.
relevanssi_live_search_alter_results (array)
This action hook can be used to modify the results. The found posts are stored in the global $wp_query object in $wp_query->posts_found.
relevanssi_live_search_base_styles (boolean)
If this filter hook returns false, the Live Ajax Search plugin won’t output the base CSS styles that control the position of the results.
relevanssi_live_search_configs (array)
This filter hook filters the configurations you can use for the different search forms to control how the search results and the spinner work.
relevanssi_live_search_get_search_form_config (string)
This filter hook controls which configuration set is used for the search form. The default value is “default“.
relevanssi_live_search_get_template_part (array, string, string)
This filter hook filters the templates used to display the search results. The array of potential templates is then given to locate_template() to find the actual template file.
relevanssi_live_search_hijack_get_search_form (boolean)
If this filter hook returns false, Live Ajax Search won’t automatically take over all search forms. If you do that, you need to manually enable the search by adding the data-rlvlive parameter to the input field with the value of true.
relevanssi_live_search_mode (string)
If this filter hook returns anything other than query_posts, Live Ajax Search will use the WP_Query mode that is generally more compatible with third-party tools. This mode uses a different results template.
relevanssi_live_search_status_location (string)
This filter hook controls where the “X posts found” status note appears in the results. The possible values are before or after. If you use any other value, the status note is not visible and appears before the results only for screen reader users.
relevanssi_live_search_plugin_whitelist (array)
If you are using the relevanssi_live_search_control_plugins_during_search filter hook, you can use this filter hook to adjust the plugins that are allowed.
relevanssi_live_search_posts_per_page (int)
This filter hook is used to modify the default posts_per_page value used if the search query doesn’t specify it. The default value is 7.
relevanssi_live_search_query_args (array)
This filter hook filters the query arguments the search passes to query_posts() to run the actual search.
relevanssi_live_search_results_template (bool|string)
This filter hook filters the location of the template file or false if no template was found.
relevanssi_live_search_template_dir (string)
This filter hook filters the name of the template directory this plugin looks in for the templates. The default value is “relevanssi-live-ajax-search“.

Modifying the search results

If you use Relevanssi to power the live search, all Relevanssi filters will also modify the live results. If you want to create a filter on relevanssi_modify_wp_query that only targets the live search or the non-live search, you can use the $_REQUEST['action'] parameter to see if you have a live search. This variable is set to relevanssi_live_search during a live search.

Questions? Issues?

The plugin support is at the WordPress.org plugin repository support forums. If you are a Relevanssi Premium user, feel free to use the Relevanssi Premium support.

You can find this plugin on GitHub. The issue tracker is an excellent place to post technical questions and suggestions.

Plugin and theme compatibility

Relevanssi

With Relevanssi, Live Ajax Search shows drafts and pending posts in the search results. This will be fixed in a future Relevanssi version.

Meanwhile, you can add this to your site to fix the problem:

add_filter( 'relevanssi_live_search_query_args', function ( $args ) {
  $args['post_status'] = 'publish,inherit'; // or just 'publish', if you don't need attachments in the results
  return $args;
} );

WPML

Relevanssi Live Ajax Search, Relevanssi and WPML do not work well together. Combining the plugins causes the search not to return any results. Relevanssi searches correctly and returns the right results, but something in the combination makes the results disappear.

This problem only happens when you use the default query_posts mode of Relevanssi Live Ajax Search. Use the WP_Query mode instead:

add_filter( 'relevanssi_live_search_mode', function() { return 'wp_query'; } );

Another way to deal with the problem is to disable the wpml_get_active_languages_filter filter function in WPML (thanks to Janw Ostendoorp):

add_filter( 'relevanssi_live_search_mode', function ( $arg ) {
	remove_filter( 'wpml_active_languages', 'wpml_get_active_languages_filter' );
	return $arg;
} );
add_action( 'relevanssi_live_search_alter_results', function () {
	add_filter( 'wpml_active_languages', 'wpml_get_active_languages_filter', 10, 2 );
} );

Polylang

Searches made with Relevanssi Live Ajax Search don’t always respect the language parameters from Polylang. If you see results from all languages instead of only the current language, you must explicitly pass the language parameter to the search.

There are a couple of ways to do that. One is to add the language parameter to the search form. For example, you can do that with the get_search_form filter hook. Another is to use the relevanssi_live_search_query_args filter hook to add the language parameter to the query.

Astra and Divi

The default settings of Relevanssi Live Ajax Search don’t work with Astra and Divi. It almost does: Live Ajax Search hijacks the form, fetches the results and displays them – but Astra and Divi hide them. I haven’t found a way to show the results with CSS alone. Fortunately, there are other solutions.

The easiest solution is this:

add_filter( 'relevanssi_live_search_add_result_div', '__return_false' );

This function restores the old default behaviour where the search results are not placed in a div inside the search form, but instead, the Live Search adds the results at the bottom of the page. This method works fine with Astra and Divi. However, this is not as good for accessibility, as now you can’t move with a tab press from the form to the results.

Here’s a more complex solution that is better for accessibility:

add_filter( 'relevanssi_live_search_hijack_get_search_form', '__return_false' );
add_filter( 'get_search_form', function( $html ) {
    global $form_number;
	
	$config = apply_filters( 'relevanssi_live_search_get_search_form_config', 'default' );
	if ( ! $form_number ) {
		$form_number = 10;
	}
	$form_id  = 'rlvlive_' . $form_number++;
	$parentel = 'data-rlvparentel="#' . $form_id . '"';
	$html     = str_replace( 'name="s"', 'name="s" data-rlvlive="true" ' . $parentel . ' data-rlvconfig="' . esc_attr( $config ) . '"', $html );
	$html     = str_replace( '</form>', '</form><div id="' . $form_id . '"></div>', $html );

	return $html;
} );

This function works in Astra and Divi and adds the results div immediately after the search form, which is better for accessibility. The results probably aren’t right next to the form, but you can move them with CSS.

Storefront

Storefront requires you to use this:

add_filter( 'relevanssi_live_search_add_result_div', '__return_false' );

Elementor

To make the Elementor Search Form widget use the Live Ajax Search, add this snippet to your site:

add_filter(
	'elementor_pro/search_form/before_input',
	function( $module ) {
		$module->add_render_attribute( 'input', [ 'data-rlvlive' => 'true'] );
	}
);

Header search doesn’t get results when the page is scrolled down

Some header formats cause the search to work when the user is at the top of the page and fail when the user scrolls down. To fix this, set the static_offset parameter to false:

add_filter( 'relevanssi_live_search_configs', function( $configs ) {
    $configs['default']['results']['static_offset'] = false;
    return $configs;
} );

Changes from SearchWP Live Ajax Search

Relevanssi Live Ajax Search is a fork of SearchWP Live Ajax Search. I forked it from version 1.6.1 because it looked like SearchWP Live Ajax Search wasn’t getting updates anymore. I also wanted to improve the Relevanssi compatibility.

Relevanssi Live Ajax Search drops all SearchWP compatibility. I also removed the search widget: it was unnecessary and outdated.