Loupe Search Block

Help visitors find the right content without leaving the page. Loupe Search Block adds live search, useful filters, and highlighted results to your WordPress site.

New here? Follow the step-by-step tutorial to build your first search page. No coding is needed for the basic setup.

Quick start · Block settings · Styling · Troubleshooting · Developer notes

See it in action

The demo shows live search, author and custom-field filters, a published-date range, sorting, and pagination.

https://github.com/user-attachments/assets/2a1d6865-4ebb-41eb-9a22-ca9ca5e46bdb

What visitors can do

• Search as they type. Results update inside the block, with matching words highlighted.
• Narrow the results. Filter by content type, category, tag, custom taxonomy, author, or custom field.
• Choose a date range. Find content published between two dates.
• Change the order. Sort by relevance, newest, oldest, or title.
• Browse more results. Move between result pages without reloading the page.

The checkbox filters are also called facets. Each value shows a matching-result count. You choose which filters visitors see.

Without JavaScript, the block still works as a standard search form. If Loupe Search's Search insights is enabled, only settled or submitted queries are counted, rather than every keystroke.

Requirements

• WordPress 6.9 or later
• PHP 8.3 or later
• Loupe Search 1.4.0 or later, installed and active

Loupe Search builds the search index; this add-on provides the search block.

Quick start

1. Install and activate Loupe Search and Loupe Search Block. Use the ready-to-install loupe-search-block.zip from Releases, not GitHub's Source code ZIP.
2. Go to Settings → Loupe Search → Fields, choose the content types to search, and save your settings.
3. Open the Dashboard tab, click Reindex now, and keep it open until indexing finishes.
4. Create or edit a page. Click +, search for Loupe Search, and insert that block.
5. Publish the page, open it on the front end, and search for a word in your published content.

Want author, date, or custom-field filters? The tutorial walks through the field settings and block switches you need.

Turning on a block switch does not enable a field in the search index. Mark the field Indexable and Filterable in Loupe Search, save, and reindex. Sorting requires Sortable too.

Block settings

Select the block and open its settings sidebar. Settings are grouped in the Search, Filters, Sorting, and Results panels and apply to that block, so different pages can have different search experiences. When a filter needs a field setting in Loupe Search, the switch's help text says which one.

The editor canvas previews the search form and controls enabled for that block. The preview is not interactive; facet values appear after a visitor searches.

You can also adjust alignment, spacing, and text/background colors with the editor's block controls, where supported by your theme.

Why might a filter be missing? It needs an eligible field marked Filterable, matching results, and its block switch enabled. With All types selected, a field must be available for every searched content type. See the troubleshooting guide.

Developer notes

The block name is loupe-search/search. The add-on communicates with Loupe Search through its public REST API only. See the architecture decision.

Translations

Norwegian Bokmål (nb_NO) is included for the editor and front end. Select Norsk bokmål under Settings → General → Site Language for visitors; the editor follows the user's profile language. Custom labels, placeholders, and field names are not translated automatically.

After changing translations, run npm run i18n:build to regenerate the bundled MO, PHP (.l10n.php) and JavaScript JSON files. After changing source strings, run npm run build and npm run i18n:make-pot first, then update the PO file.

Add these filters in a custom plugin or your child theme:

// Reorder or remove facet fields, e.g. a geo field that cannot be listed as values.
add_filter( 'loupe_search_block_facet_fields', function ( array $facets, array $filterable ) {
    return array_values( array_diff( $facets, [ 'my_geo_field' ] ) );
}, 10, 2 );

// Change a facet's heading.
add_filter( 'loupe_search_block_facet_label', function ( string $label, string $field ) {
    return 'loupe_color' === $field ? 'Colour' : $label;
}, 10, 2 );

Fields returned by loupe_search_block_facet_fields that are not Filterable are dropped.

npm install
composer install
npm run build      # or: npm start
npm test           # Jest
composer test      # PHPUnit
npm run lint:js

License

GPL-2.0-or-later. See LICENSE.