Customizing the autosuggest feature

Some website owners might feel the need for customizing autosuggest’s look and functionality, such as change the number of shown results, add suggestion’s featured image, filter suggestions based on category or add branding to the suggestion container. This article reviews the required hooks for these purposes and shows some examples. For a tutorial on the feature’s explanation and how to enable it refer to this article.

Connecting Autosuggest to Your WordPress Theme’s Search Bar

When enabled, ElasticProbe autosuggest automatically attaches to any input[type="search"] elements on your site, as well as elements with the .ep-autosuggest or .search-field classes. To integrate autosuggest into additional elements, simply add your custom selectors (comma-separated) in WordPress Dashboard → ElasticProbe → Features → Autosuggest → Settings → Autosuggest Selector.

You can also modify or remove the default selectors with the eprobe_autosuggest_default_selectors filter. For example, using __return_empty_string() removes the defaults so that only the selectors you define in settings are used.

				
					add_filter( 'eprobe_autosuggest_default_selectors', '__return_empty_string' );

Adding a Loading Indicator

While suggestions are being fetched as the user types, ElasticProbe adds an .is-loading class to the parent <form>.

				
					<form role="search" method="get" action="<?php echo esc_url( home_url( '/' ) ); ?>">
	<label>
		<span class="screen-reader-text">Search for:</span>
		<input type="search" value="<?php echo get_search_query(); ?>" name="s">
	</label>
	<input type="submit" value="Search">
	<img decoding="async" src="<?php echo esc_url( get_theme_file_uri( 'images/loading.gif' ) ); ?>" width="32" height="32" class="loading-indicator">
</form>

You can style this state—for example, to display a loading GIF in your theme’s search form—by targeting .is-loading in your CSS.

				
					.loading-indicator {
	display: none;
}

.is-loading .loading-indicator {
	display: block;
}

Customizing Autosuggest’s Suggestion Markup

You can change the HTML for individual autosuggest items via the ep.Autosuggest.itemHTML JavaScript hook. From your WP theme (or plugin), you can add or remove fields like post date or categories.

The hook passes the original HTML as a string, plus three parameters with suggestion data.

Name	Type	Description
itemHTML	string	The suggestion HTML as a string.
option	object	The Elasticsearch record for the suggestion.
index	number	The index of the suggestion in the results set.
searchText	string	The search term.

The filter must return the modified HTML string, keeping key attributes (class, id, role, aria-selected, data-url, tabindex) intact so autosuggest works correctly. Here is an example to add the post date to the suggestion.

				
					const autosuggestItemHTML = (itemHTML, option, index, searchText) => {
	const text = option._source.post_title;
	const url = option._source.permalink;
	const postDate = new Date(option._source.post_date).toLocaleString('en', { dateStyle: 'medium' })

	return `<li class="autosuggest-item" role="option" aria-selected="false" id="autosuggest-option-${index}">
		<a href="${url}" class="autosuggest-link" data-url="${url}" tabindex="-1">
			${text} (${postDate})
		</a>
	</li>`;
};
wp.hooks.addFilter('ep.Autosuggest.itemHTML', 'myTheme/autosuggestItemHTML', autosuggestItemHTML);

Customizing the Suggestions List Markup

For changes to the entire suggestions list, use the ep.Autosuggest.listHTML hook. ep.Autosuggest.listHTML filters receive the following parameters:

Name	Type	Description
listHTML	string	The list HTML as a string.
options	array	The Elasticsearch records for the suggestions.
input	Element	The input element that triggered Autosuggest.

This allows you to append, prepend, or alter the full list—such as adding a “View All Results” link.

				
					const autosuggestListHTMLFilter = (listHTML, options, input) => {
	const allUrl = new URL(input.form.action);
	const formData = new FormData(input.form);
	const urlParams = new URLSearchParams(formData);

	allUrl.search = urlParams.toString();

	const url = allUrl.toString();

	listHTML += `<li class="autosuggest-item" role="option" aria-selected="false" id="autosuggest-option-all">
		<a href="${url}" class="autosuggest-link" data-url="${url}" tabindex="-1">
			View All Results
		</a>
	</li>`;

	return listHTML;
};

wp.hooks.addFilter('ep.Autosuggest.listHTML', 'myTheme/autosuggestListHTMLFilter', autosuggestListHTMLFilter);

Note: the class, role, aria-selected and tabindex attribute must match with their previous value and should not be altered. The href and data-url attributes should be set to the URL that the item is linking to.

Customizing the Suggestions Container

The container markup for autosuggest can be modified using the ep.Autosuggest.element hook. This gives you access to the element before the container and the container itself, allowing you to add branding, messages, or custom wrappers directly from your WP theme or plugin. The ep.Autosuggest.element filter’s parameters are:

Name	Type	Description
element	Element	The autosuggest container element.
previousElement	Element	The element the container will be inserted after.

This is an example which adds “Powered by ElasticProbe” to autosuggest container.

				
					const autosuggestElementFilter = (element, previousElementput) => {
	const poweredBy = document.createElement('div');

	poweredBy.textContent = 'Powered by ElasticProbe';

	element.appendChild(poweredBy);

	return element;
};

wp.hooks.addFilter('ep.Autosuggest.element', 'myTheme/autosuggestElementFilter', autosuggestElementFilter);

Customizing the Autosuggest Query

Before sending the Elasticsearch request for fetching the autosuggest results, ElasticProbe runs the ep.Autosuggest.query hook. You can intercept this to add filters (like category restrictions) or other query changes. The following are the parameters of ep.Autosuggest.query hook.

Name	Type	Description
query	object	The Elasticsearch query as a JavaScript object.
searchText	string	The search term.
input	Element	The input element that triggered Autosuggest.

The filter must return a valid ElasticSearch query as an object. The following example uses the value of wp_dropdown_categories() field to filter the search results by category.

				
					const autosuggestQueryFilter = (query, searchText, input) => {
	const formData = new FormData(input.form);
	const category = formData.get('cat');

	if (category) {
		query.post_filter.bool.must.push({
			term: {
				'terms.category.term_id': parseInt(category, 10),
			},
		});
	}

	return query;
};

wp.hooks.addFilter('ep.Autosuggest.query', 'myTheme/autosuggestQueryFilter', autosuggestQueryFilter);

Customizing Autosuggest’s Navigation Behavior

The ep.Autosuggest.navigateCallback hook lets you control what happens when a user selects a suggestion. You can add URL parameters, open results in a new tab, or trigger other custom actions.

The filter accepts the following parameters and does not return any value.

Name	Type	Description
searchTerm	string	The search term.
url	string	URL to navigate to.

In this example a “cyperss” query argument with the value of “foobar” is added to the URL.

				
					const myNavigateCallback = (searchTerm, url) => {
	let cypressQueryArg = new URLSearchParams(window.location.search)
	cypressQueryArg.set('cypress', 'foobar');
	var newURL = url + '?' + cypressQueryArg.toString();
	window.location.href = newURL;
};
wp.hooks.addFilter(
	'ep.Autosuggest.navigateCallback', 'myTheme/myNavigateCallback',
	() => myNavigateCallback,
);

Customizing Autosuggest Result Limits

By default, autosuggest displays a set number of results per query. You can adjust this using the eprobe_autosuggest_query_args filter:

eprobe_autosuggest_query_args — Hook for changing autosuggest query arguments.
$args['posts_per_page'] = 5; — Sets the number of displayed results.
Return the modified $args array to apply changes.

				
					add_filter(
	'eprobe_autosuggest_query_args',
	function( $args ) {
		$args['posts_per_page'] = 5;
		return $args;
	}
);

If changes don’t take effect immediately, go to:
WordPress Dashboard → ElasticProbe → Search Fields & Weighting and click Save to sync with your ElasticProbe.com account.

Table of Contents