Live Search widget

The Live Search widget sends the visitor's query to WordPress' REST API and renders the results without a page reload. Everything the widget does is built on top of a real search form, so if JavaScript is unavailable the form still submits and the theme's native search results page opens.

General section

Results display mode is the most important choice; it changes the whole experience and the list of available controls. See the display modes page.

Display modes

The live search widget has two display modes, and this single control decides where results are shown, which extra controls are available and how visitors navigate them.

Comparing the two modes

List mode

The default mode. The panel opens after the visitor types two or more characters and closes on an outside click, with Escape, or when the widget loses focus.

[ Search field ▾ ]
└──────────────────────────────┐
│  8 results            All text │
│  ┌────┐ Result title           │
│  │ img│ Excerpt…                │
│  └────┘ 2026-09-01             │
│  ┌────┐ Result title           │
└──────────────────────────────┘

1. The visitor clicks the field

   If a valid query is already in the field and results are still loaded, the panel opens.

2. The visitor types

   After 250 milliseconds the request is sent and the panel opens.

3. A result is picked with the keyboard or the mouse

   The up and down arrows move between results and Enter opens the selected one.

4. The panel closes with an outside click or Escape

   A second Escape clears the text in the field.

Page mode

The results region is always visible inside the widget, so it behaves like a real search page: the visitor types a query and results appear below in the same view.

Columns, masonry and equal height

Choosing a template in Page mode

When “Template choice” is set to Custom, the widget sends the template id to the REST route and each result is rendered with your Elementor template:

1. Build the template in the library

   “Templates → Saved Templates”; the template must be published.

2. Select it in the widget

   “Template choice” → Custom, then pick the template.

3. Check the output

   The root gets the wgcr-search--tpl class and the template's own CSS loads once.

Details on the Elementor templates page.

Behaviour differences that are easy to miss

Selecting with the mouse

• List mode: moving the mouse over a result marks it as “selected” so Enter opens it.
• Both modes with an Elementor template: when results are rendered by a custom template (wgcr-search-item--tpl), hovering no longer marks a result as selected and the selected styling is not applied — the template has its own links and styles, and overlapping them would break clicks. If a templated result has no link of its own, clicking the card opens that result.

Focus after pagination

When you change page with the keyboard, focus returns to the button you pressed (previous, next, or the current page number) after the new results are rendered. Keyboard users therefore never lose their place in the pagination bar.

Infinite scroll

In Page mode a sentinel element (.wgcr-search-sentinel) measures the end of the results with IntersectionObserver against the browser window, so loading more does not require scrolling inside a panel. In List mode the panel's own scroll is what counts.

Accessibility in both modes

Full details on the accessibility page and the keyboard shortcuts page.

Style differences

Because both modes share the same root class (.wgcr-search), you can write one CSS rule for the shared parts and add mode-specific rules with the modifier classes.

Which mode to choose

Elementor templates

Besides the built-in card, the live search can render each result with an Elementor template you designed yourself. This gives you full control over the result markup while the plugin keeps handling the query, pagination and accessibility.

Preparing the template

1. Create a template in the library

   “Templates → Saved Templates → Add New”, type “Section”.

2. Design one result card

   Use Dynamic Tags for the post fields; the template is rendered in the context of each result.

3. Publish the template

   An unpublished template cannot be selected.

4. Select it in the widget

   “Template choice” → Custom, then pick the template from the list.

What happens during a search

When a template is selected, the request carries the template id:

GET /wp-json/wgcr/v1/search?q=course&limit=12&type=post&template=42

The server renders the template for every matching post:

$plugin   = \Elementor\Plugin::instance();
$document = $plugin->documents->get( $template_id );
$html     = $plugin->frontend->get_builder_content_for_display( $template_id );

The response then includes an html field per result alongside id, title, link, thumb, excerpt and date. The client inserts that HTML directly, which is why no escaping happens twice.

Checking for visible content

Before the rendered template is used, the plugin strips tags and checks whether anything visible is left:

$visible = trim( wp_strip_all_tags( $html ) );

If the result is empty — because the template has no content, or its conditions do not match — the plugin falls back to the default card. This prevents the results area from turning into a blank block.

How the template CSS is loaded

Elementor prints each template's CSS with enqueue_css. Since search results are injected after the page has loaded, the plugin takes two steps:

1. Inline critical CSS: post_css for the template is printed inline once per page, so the injected markup is styled immediately.
2. Register the template style handle: elementor-post-{id}.css is added to the widget's style dependencies so it loads on pages that contain the widget.

Entry animations and handlers

Elementor elements often carry animations or interactions (hover effects, counters, carousels). Because the markup is injected after page load, those handlers are not bound automatically. The plugin therefore runs:

if ( window.elementorFrontend ) {
	window.elementorFrontend.elementsHandler.runReadyTrigger( container );
}

on the injected results container, so animations and interactions defined in the template work as if the content had been printed server-side.

Templated results and interaction

Recommended template pattern

┌──────────────────────────────────────────┐
│ ┌──────┐  Title (H4 or H3)               │
│ │ thumb│  Excerpt (2 lines, clamp)       │
│ └──────┘  Category • Date                │
└──────────────────────────────────────────┘

Template troubleshooting

Query and filters

Every search in the plugin ends in one WP_Query. This page shows what goes into that query, what you can control without writing code, and the two filters that let you change the query on the server.

Base query arguments

Filters without code

The tax_query structure

With terms_op="include" several terms are combined with an OR relation:

'tax_query' => array(
	'relation' => 'OR',
	array(
		'taxonomy' => 'category',
		'field'    => 'term_id',
		'terms'    => array( 12, 18 ),
		'operator' => 'IN',
	),
),

With terms_op="exclude" a single entry excludes the terms:

'tax_query' => array(
	array(
		'taxonomy' => 'category',
		'field'    => 'term_id',
		'terms'    => array( 12, 18 ),
		'operator' => 'NOT IN',
	),
),

The terms format

terms="12,18"                    → category:12, category:18
terms="category:12,post_tag:7"   → mixed taxonomies
terms="product_cat:33"           → a WooCommerce category

Each item is split on the colon; when the taxonomy part is missing, category is assumed. Ids are cast to positive integers and anything that is not a number is dropped.

Server-side filters

Two filters let you change the final arguments:

The general filter runs first, so the id-specific one always has the final say.

Where to write them

/* A small custom plugin, or the theme's functions.php */
add_filter( 'wgcr_search_query_args', 'my_search_args', 10, 3 );

function my_search_args( $args, $query_id, $request ) {
	/* your changes */
	return $args;
}

Practical examples

Search several post types at once

add_filter( 'wgcr_search_query_args', function ( $args ) {
	$args['post_type'] = array( 'post', 'page', 'course' );
	return $args;
} );

Restrict one widget by Query ID

add_filter( 'wgcr_search_query_args/featured', function ( $args, $request ) {
	$args['meta_query'] = array(
		array( 'key' => 'featured', 'value' => 'yes' ),
	);
	return $args;
}, 10, 2 );

Combine terms with AND instead of OR

add_filter( 'wgcr_search_query_args', function ( $args ) {
	if ( ! empty( $args['tax_query'] ) && 'OR' === ( $args['tax_query']['relation'] ?? '' ) ) {
		$args['tax_query']['relation'] = 'AND';
	}
	return $args;
} );

Search post titles only

add_filter( 'posts_search', function ( $search, $query ) {
	if ( ! empty( $query->get( 'wgcr_title_only' ) ) ) {
		global $wpdb;
		$term = '%' . $wpdb->esc_like( $query->get( 's' ) ) . '%';
		$search = " AND {$wpdb->posts}.post_title LIKE '{$term}' ";
	}
	return $search;
}, 10, 2 );

add_filter( 'wgcr_search_query_args', function ( $args, $query_id ) {
	if ( 'titles' === $query_id ) {
		$args['wgcr_title_only'] = 1;
	}
	return $args;
}, 10, 2 );

Exclude a category site-wide

add_filter( 'wgcr_search_query_args', function ( $args ) {
	$args['tax_query'][] = array(
		'taxonomy' => 'category',
		'field'    => 'term_id',
		'terms'    => array( 99 ),
		'operator' => 'NOT IN',
	);
	return $args;
} );

Performance notes

Pagination

Pagination only matters when the number of matches is larger than “Items per page”. The widget offers four types, and each one uses a different mechanism: replacing the current results or appending new ones.

The four pagination types

Numbers is the most complete type: a bar with page buttons, previous and next links and an accessible “Page X of Y” text. Because it needs the total number of results, the request carries page and the server returns the X-WP-Total and X-WP-TotalPages headers.

Previous and next uses the same mechanism but only renders two buttons, which suits narrow layouts.

Load on click appends the next page to the existing list with a button click. The visitor keeps their scroll position and can go back to earlier results without a request.

Load on scroll replaces the button with an IntersectionObserver: when the sentinel element comes within about 300 pixels of the bottom of the viewport, the next page loads automatically.

The page bar markup

<nav class="wgcr-search-pager" aria-label="Pagination">
	<button type="button" class="wgcr-search-pg wgcr-search-pg--prev">Previous</button>
	<button type="button" class="wgcr-search-pg is-active" aria-current="page">1</button>
	<button type="button" class="wgcr-search-pg">2</button>
	<button type="button" class="wgcr-search-pg">3</button>
	<button type="button" class="wgcr-search-pg wgcr-search-pg--next">Next</button>
	<span class="wgcr-search-pageof" aria-live="polite">Page 1 of 3</span>
</nav>

Related controls

The “Spacer” control only adds vertical space before the bar; it does not change behaviour.

How the page count is computed

const totalPages = Number( response.headers.get( 'X-WP-TotalPages' ) ) || 1;
const current    = Number( params.get( 'page' ) ) || 1;

The server sends these headers only when page is greater than 0. That means a plain request without page returns no pagination headers, which is why the widget always sends page when a pagination type is active.

Infinite scroll

With load_on_scroll the widget builds a sentinel element at the end of the list:

const io = new IntersectionObserver( ( entries ) => {
	if ( entries[ 0 ].isIntersecting && ! loading && hasMore ) {
		loadPage( current + 1, true );
	}
}, { rootMargin: '300px' } );

Keyboard behaviour

After a page change, focus returns to the button the visitor pressed — not to the top of the page — so screen-reader users and keyboard users keep their place in the interface.

Performance notes

• Items per page: the default 12 is a good balance. Above 24 results the payload grows noticeably, especially with thumbnails.
• Thumbnails: every result with an image adds a request (unless cached). Turning “Show thumbnail” off makes long lists much lighter.
• Templates: a custom Elementor template renders each result on the server, so more items per page means more work per request. With a heavy template keep “Items per page” at 6 to 9.
• Debounce: queries are debounced at 250 ms and every in-flight request is aborted with AbortController, so fast typing does not produce a burst of requests.

Choosing a type

Styling

In Page mode, extra sections control the container and the cards (background, spacing, border radius, shadow and typography).

The search widget is styled in two layers: Elementor style controls (which print inline CSS on the widget) and CSS classes you can target from your theme. This page covers both, plus ready-made snippets.

CSS variables

The plugin defines component-scoped CSS custom properties on each .wgcr-search root. They are not site-wide theme variables; they provide defaults for the widget’s accent colours, borders, radius and responsive column count. Override them on the root of one widget to change only that instance.

For example, change the palette for one widget:

.wgcr-search {
	--wgcr-blue: #4f46e5;
	--wgcr-navy: #3730a3;
	--wgcr-ink: #0f172a;
	--wgcr-slate: #64748b;
	--wgcr-line: #e2e8f0;
	--wgcr-radius: 10px;
}

The classes below are the stable hooks:

Elementor style controls

Search field

Results box

Items

Columns, masonry and equal height

These three settings only appear in Page mode and map directly to root classes:

On screens narrower than 782px the grid drops to a single column automatically, and below 480px the thumbnail shrinks so results stay readable on small phones.

Ready-to-use snippets

A card with a soft shadow and a coloured edge

.wgcr-search-item {
	border-radius: 12px;
	box-shadow: 0 2px 12px rgb(15 23 42 / 8%);
	border-inline-start: 3px solid #2563eb;
	transition: transform .18s ease, box-shadow .18s ease;
}
.wgcr-search-item:hover {
	transform: translateY(-2px);
	box-shadow: 0 8px 24px rgb(15 23 42 / 12%);
}

A dark panel

.wgcr-search-panel {
	background: #0f172a;
	border-color: #1e293b;
	color: #e2e8f0;
}
.wgcr-search-title { color: #f8fafc; }
.wgcr-search-excerpt { color: #94a3b8; }
.wgcr-search-item:hover { background: #1e293b; }
.wgcr-search-msg { color: #64748b; }

A panel as wide as the field in List mode

.wgcr-search--modal .wgcr-search-panel {
	position: absolute;
	inset-inline: 0;
	width: 100%;
	max-width: none;
}

Removing the thumbnail for a compact layout

.wgcr-search-thumb { display: none; }
.wgcr-search-item { padding: 8px 12px; }
.wgcr-search-link { gap: 0; }

Important notes

• Do not edit search.css directly: the file is replaced on every update. Put your CSS in the theme's stylesheet or in Elementor's “Custom CSS”.
• Respect prefers-reduced-motion: if you add transitions, disable them for visitors who asked for reduced motion:

@media (prefers-reduced-motion: reduce) {
	.wgcr-search-item, .wgcr-search-panel { transition: none !important; }
}

• Keep contrast: the default colours were chosen for at least 4.5:1 contrast on the body text. If you recolour the panel, re-check contrast (see the accessibility page).
• RTL and LTR: all layout rules use logical properties (inset-inline, margin-inline, border-inline-start), so the same CSS works in both directions. Avoid physical properties such as left or margin-right in your overrides.

Result structure

With the default template each result looks like this:

<article class="wgcr-search-item">
	<a class="wgcr-search-link" href="https://example.com/?p=42">
		<img class="wgcr-search-thumb" src="…" alt="Post title" width="72" height="72">
		<h4 class="wgcr-search-title">Post title</h4>
		<p class="wgcr-search-excerpt">A short text…</p>
		<time class="wgcr-search-date" datetime="2026-09-01">2026-09-01</time>
	</a>
</article>

In custom template mode the markup is whatever your Elementor template produces, and wgcr-search--tpl is added to the root so you can style it separately.

JavaScript configuration

Before search.js, a configuration object is printed inline:

window.WGCRSearch = {
	restUrl: 'https://example.com/wp-json/wgcr/v1/search',
	homeUrl: 'https://example.com/',
	minChars: 2,
	maxResults: 50,
	i18n: {
		noResults: 'No results found.',
		found: 'results',
		error: 'Error fetching results.',
		prev: 'Previous',
		next: 'Next',
		page: 'Page',
		pageOf: 'of'
	}
};

Client-side behaviour

The flow: the visitor types → 250 ms are waited → if the query is shorter than 2 characters the panel is emptied and cleared → otherwise the previous request is aborted and a new one is sent → results are rendered → the status message (“N results”) is read out to screen readers.

Working without JavaScript

The widget's form is a real GET form whose action is the site home, with an s field and a hidden post_type field. So if JavaScript is disabled, submitting the form takes the visitor to WordPress' own search results page for that post type. This is the pattern recommended for accessibility and SEO: progressive enhancement, not a hard dependency on a script.

Data attributes on the widget root

The JavaScript reads its settings from the data-* attributes on the root element, so if you build the widget with dynamic templates or PHP code, include all of them:

Complete control reference

Every content control of the widget, in panel order. Style controls are listed in “Style sections” above.

Troubleshooting