README

A search enhancement plugin for WordPress that builds a fast, typo-tolerant index and exposes a developer-friendly API so you can build your own search UI. Loupe Search works out of the box with WordPress’s standard search.

Renamed from WP Loupe. Loupe Search is the successor to the WP Loupe plugin. Existing installs upgrade seamlessly, and the legacy filters, REST namespace, CLI command, and index folder still work as deprecated aliases. See Renamed from WP Loupe for details.

Quick Links

Overview

Loupe Search replaces WordPress core search:

Queries a dedicated SQLite index instead of the posts table
Tolerates misspellings, and supports phrase matching and exclusion operators
Keeps the index in sync as content is created, updated, and deleted
Exposes a stable REST API for custom search experiences

Integrating with AI agents or automation? Loupe Search registers native abilities via the WordPress Abilities API.

Features

Fast index-backed search for configured post types
Typo-tolerant matching, phrase matching, and exclusion operators
Exclude individual posts from search from the post list (column, Quick Edit, bulk actions) or the editor sidebar — hides them from results, not access control
Per-field weighting, filterable fields, sortable fields (configured in Settings)
Opt-in match highlighting on the default search results (see Filters)
Developer-facing REST API for building custom UIs, with filters, facets, geo search, and result highlighting/snippets
Native AI agent integration via the WordPress Abilities API
Opt-in Search insights: top searches and searches without results, stored as privacy-friendly daily totals (no IP, user or browser data)

Technical Requirements

PHP 8.3 or higher
SQLite 3.35+ (required by Loupe 0.13.x)
PHP extensions: pdo_sqlite, intl, mbstring
WordPress 7.0+

About the PHP extensions: pdo_sqlite provides the SQLite driver Loupe uses to store and query the search index; intl powers locale-aware tokenizing, collation, and typo tolerance; and mbstring ensures multibyte (UTF-8) text is handled correctly during indexing and search. All three are required, but they are enabled by default on most modern PHP installations and shared hosts, so no action is usually needed. If your host is missing one, contact them or enable it in your PHP configuration.

Installation

Install from WordPress.org
- In your WordPress admin, go to Plugins > Add New
- Search for "Loupe Search"
- Click "Install Now", then "Activate"
Quick Install
- Download loupe-search.zip
- Upload via WordPress Plugins > Add New > Upload Plugin
Composer Install
```
composer require soderlind/loupe-search
```
Post-Installation
- Activate the plugin
- Go to Settings > Loupe Search
- Click "Reindex" to build the initial search index (runs in batches; safe for large sites)

Settings

You can configure Loupe Search's search behavior and performance via the WordPress admin: Settings > Loupe Search.

General Settings

Post Types

Select which post types to include in the search index.

Field Weight

Weight determines how important a field is in search results:

Higher weight (e.g., 2.0) makes matches in this field more important in results ranking.
Default weight is 1.0.
Lower weight (e.g., 0.5) makes matches less important but still searchable.

Filterable Fields

Filterable fields can be used to refine search results:

Enable this option to allow filtering search results by this field's values.
Best for fields with consistent, categorized values like taxonomies, status fields, or controlled metadata.
Examples: categories, tags, post type, author, or custom taxonomies.

Note: Fields with highly variable or unique values (like content) make poor filters as each post would have its own filter value.

Sortable Fields

Sortable fields can be used to order search results:

Enable this option to allow sorting search results by this field's values
Works best with numerical fields, dates, or short text values
Examples: date, price, rating, title

Advanced Settings

Loupe Search provides advanced configuration options to fine-tune your search experience:

Prefix Search

Configure prefix search behavior. Prefix search allows finding terms by typing only the beginning (e.g., "huck" finds "huckleberry").
Prefix search is only performed on the last word in a search query. Prior words must be typed out fully to get accurate results. E.g. my friend huck would find documents containing huckleberry - huck is my friend, however, would not.

Typo Tolerance

Enable Typo Tolerance: When enabled, searches will match terms with minor spelling errors.
First Character Double Counting: When enabled, typos in the first character of a word will count as two errors instead of one.
Typo Tolerance for Prefix Search: Allows typo tolerance in partial word searches.
Alphabet Size: Define the size of the alphabet for typo calculations.
Index Length: Configure the maximum length of indexed terms.
Typo Thresholds: Set the minimum word length required for allowing different numbers of typos.

Query Parameters

Maximum Query Tokens: Limits the number of words processed in a search query (default: 12).
Minimum Prefix Length: Sets the minimum character length before prefix search activates (default: 3).

Languages

Configure which languages the search index should optimize for. Default is English ('en').

These advanced settings can be accessed in the WordPress admin under Settings > Loupe Search > Advanced tab.

Search insights

Settings > Loupe Search > Search insights shows what visitors search for: the top 20 searches and the top 20 searches without results for the last 7, 30 or 90 days, plus the average number of results. It is off by default.

Only daily totals per search query are stored (how often it was searched and how many results it returned). No IP address, user, browser details or time of day.
Only front-end visitor searches are counted: the WordPress search page, and REST searches that send countSearch: true. Administrators, bots, WP-CLI and admin screens are skipped.
Queries that look like an email address or phone number, or are longer than 100 characters, are discarded.
Data is kept for 90 days by default (configurable) and purged daily. Turning the feature off keeps existing data; use Clear all data to delete it. Suggested privacy policy text is added under Settings > Privacy.

Reindexing

Reindexing rebuilds the index for your configured post types.

Admin UI: Settings → Loupe Search → click Reindex (runs in batches to avoid timeouts)

WP-CLI (recommended for large sites):

 wp loupe-search reindex

Optional flags:

 wp loupe-search reindex --post-types=post,page --batch-size=1000

After a plugin update that makes existing indexes out of date (for example a new bundled Loupe version), Loupe Search rebuilds them automatically in the background with WP-Cron. Search keeps using the old index until the rebuild finishes.

FAQ

How does it handle updates to posts?

The search index automatically updates when content is created, modified, or deleted.

Will it slow down my site?

No. Loupe Search uses a separate, optimized search index and doesn't impact your main database performance.

Can I customize what content is searchable?

Yes, using filters you can control exactly what content gets indexed and how it's searched. To hide a single post, mark it as excluded from the post list or the editor sidebar; for rules (e.g. a category or an SEO plugin's noindex) see loupe_search_is_indexable. Excluding a post only removes it from search results — it stays public at its URL.

Does it work with custom post types?

Yes, you can select which post types to include in the Settings page or via filters.

Building Your Own Search UI

Loupe Search works out of the box with WordPress’s standard search. If your theme uses the normal search flow (e.g. a search form that routes to the built-in search results page), Loupe Search will power the results automatically — no custom UI required.

Loupe Search intentionally does not ship a front-end search block/shortcode UI. For a ready-made one, install the Loupe Search Block add-on. If you want a custom search experience (autocomplete, filters/facets, geo, custom sorting, etc.), build the UI you want and query Loupe Search via the REST API.

Start here: docs/search-api.md

REST API

Loupe Search exposes search via REST endpoints:

POST /wp-json/loupe-search/v1/search (recommended; supports JSON filters, facets, geo, explicit sorting, and search-result highlighting/snippets)
GET /wp-json/loupe-search/v1/search?q=... (legacy; kept for backward compatibility)

The old wp-loupe/v1 namespace still works as a deprecated alias. See Renamed from WP Loupe.

Developer documentation (schema + examples + Gutenberg block example): docs/search-api.md

Add-ons

Loupe Search Block — A search block with live results as you type, a post type filter, category and tag facets, sorting and highlighted snippets. Falls back to a plain search form without JavaScript. Requires Loupe Search 1.4.0+.
Loupe Cross-Site Search — Search across every site in a WordPress multisite network from a single hub. It mirrors each site's public content into one combined index and ships a ready-to-use Cross-Site Search block with site and post-type facets, sorting, and highlighted snippets. Requires WordPress multisite 7.0+ and Loupe Search active on the network.
Loupe Semantic Search — Adds semantic retrieval to Loupe Search. Hybrid (keyword + semantic) search finds posts by meaning as well as by words, in the front-end search, the REST API and Loupe Search Block. Abilities return RAG passages with sources for AI agents. Embeddings come from a provider you connect through WordPress 7 AI Connectors. Requires WordPress 7.0+, Loupe Search 1.5.0+ and the AI plugin 1.5.0+.
VMFA Search — Supercharges the native Media Library search field with fast, typo-tolerant search across title, filename, alt text, caption, and description. Requires the Virtual Media Folders plugin.

AI Agent Integration (WordPress Abilities API)

Loupe Search registers two abilities via the WordPress Abilities API (WordPress 6.9+) so AI agents and automation tools can discover and use search functionality natively — no extra Loupe Search configuration required:

loupe-search/search — Typo-tolerant full-text search across indexed post types. Supports phrase matching and exclusion; all words must match, falling back to any word when nothing does. Publicly accessible.
loupe-search/get-post — Retrieve a single published post by ID. Publicly accessible.

Both abilities are discoverable through the standard WordPress Abilities registry and exposed via REST (show_in_rest).

Connecting an AI agent

For an AI agent to use these abilities, install and activate the MCP Adapter plugin. It exposes registered abilities to agents over the Model Context Protocol (MCP).

The legacy wp-loupe/* abilities (category wp-loupe) still work as deprecated aliases. See Renamed from WP Loupe.

Upgrading from the MCP server? The experimental MCP server, token service, and WP-CLI token commands were removed in 0.8.5. See the MCP → Abilities API migration guide.

Filters

Filters let you change what gets indexed, how it is searched, how results are returned and highlighted, and which searches Search insights counts. The Filters reference lists every filter and action with its arguments, defaults, examples, recipes, and when to reindex.

Filters use the loupe_search_* prefix; the old wp_loupe_* names still work as deprecated aliases. See Renamed from WP Loupe.

Testing

PHPUnit:
```
 composer test
```
Pest (runs using the PHPUnit config):
```
 composer test:pest
```

Acknowledgements

Loupe Search is built upon Loupe. Loupe is licensed under the MIT license.

Copyright and License

Loupe Search is open-source software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.

Loupe Search is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for more information.

soderlind / loupe-search

Package info

Security

Fund package maintenance!

Statistics