PrismSearch — Complete Guide
Everything you need to configure, extend and customise PrismSearch on your WordPress site.
Content Indexing
Choose which public content sources and taxonomy terms PrismSearch indexes, which metadata is returned to the frontend, and, with Pro, which metadata is added to the searchable index.
Content sources to index
Select the public post types that should be indexed and returned by search. The default selection is Posts and Pages, but the current plugin also allows any registered public custom post type.
This can include products, portfolios, events and other public content types. Only selected post types are included in search results and live index updates.
Taxonomies to index
Select public taxonomies whose terms should be indexed as separate search results. A matching term links to its term archive page.
Leave this setting empty if you want search results to contain post-type content only.
Frontend search modes Pro
PrismSearch Pro provides two frontend search modes.
The default REST API endpoint uses the normal WordPress REST request lifecycle and offers the broadest compatibility with themes and plugins.
The optional Direct Pro endpoint sends requests to pro/search.php and loads WordPress with SHORTINIT.
Changing the endpoint does not change the indexed content and does not require an index rebuild.
Direct endpoint performance Pro
The Direct Pro endpoint avoids most of the normal WordPress bootstrap process, making it significantly faster than the standard REST API endpoint.
Because it searches PrismSearch’s prebuilt inverted index, query processing can remain below one millisecond on a properly configured server, even with more than 100,000 indexed posts.
Complete HTTP response time still depends on the server, database, network latency and hosting environment.
Searchable meta keys Pro
This field appears after PrismSearch Pro has been registered. Search the available post-meta keys and select the values that should be added to the searchable index.
Use it for ACF fields, SKU, EAN, brand, model and other stored metadata. The selector scans metadata belonging to the currently selected post types.
Frontend meta keys
Select meta keys whose values should be included in frontend search responses and rendered in the live result list.
Frontend meta values are display-only unless the same key is also selected under Searchable meta keys. Changing display-only frontend meta keys does not require rebuilding the index.
Frontend Settings
Control when the live search starts, how many results it returns and how it integrates with the normal WordPress search page.
Minimum characters
Search starts after the visitor types the configured number of characters. The default is 2, and the accepted range is 1 to 10.
The value can be overridden for an individual shortcode with min_chars.
Results limit
Sets the maximum number of live results returned per request. The default is 8, and the accepted range is 1 to 20.
The value can be overridden for an individual shortcode with limit.
Disable frontend CSS
By default PrismSearch loads assets/frontend.css. Enable this option when your theme provides all search-box and result styling.
You can also control stylesheet loading programmatically:
add_filter( 'prismsearch_load_frontend_css', '__return_false' );Redirect on Enter
When enabled, pressing Enter in the live search input opens the full WordPress search results URL for the typed query, for example /?s=example.
This setting controls the redirect only. It does not automatically replace the WordPress search query unless Override default WordPress search is also enabled.
Override default WordPress search
When enabled, the main WordPress search query uses PrismSearch post results instead of the default WordPress text-search SQL.
The override currently considers up to 200 indexed post-type results and preserves PrismSearch result order. Indexed taxonomy terms remain available in live search but are not inserted into the standard WordPress posts loop.
WooCommerce price formatting Pro
When PrismSearch Pro is registered and WooCommerce is available, selected price metadata is formatted with the store currency symbol, currency position, decimal separator, thousands separator and decimal count.
Select the required keys under Frontend meta keys, for example _price, _regular_price or _sale_price. These fields are not selected automatically.
WCML multi-currency Pro
When WCML exposes an active frontend currency, PrismSearch includes that currency and its available exchange rate in Pro search requests and resolves selected price values for the active currency where possible.
NLP & Language
Choose the processor used to normalise and tokenise search text. PrismSearch includes 36 bundled language processors.
NLP language
Select the primary language used for tokenisation and search processing. Language processors can provide normalisation, stopword handling and language-specific token processing.
Bundled processors include English, German, French, Spanish, Portuguese, Italian, Dutch, Polish, Romanian, Russian, Ukrainian, Japanese, Chinese, Korean, Arabic, Persian, Hebrew, Thai and additional European and Asian languages.
Multilingual indexing Pro
After Pro registration, enable multilingual support and select the languages that should be indexed. PrismSearch stores a language mapping for each indexed post and taxonomy term.
WPML and Polylang are used automatically when available. When an object-specific language cannot be resolved, the configured NLP language is used as the fallback.
Language-aware frontend filtering Pro
When multilingual support is enabled, frontend search resolves the current language and filters matching objects and terms to that language before the result limit is applied.
The Language panel also displays the language currently detected for frontend filtering.
Fuzzy Search
Fuzzy matching is an optional fallback that searches nearby indexed tokens when normal matching returns too few results.
Enable fuzzy matching
When enabled, PrismSearch first runs its normal token search. The fuzzy pass runs only when the normal result count is lower than Trigger below results.
With the default edit distance of 1, examples such as serch → search or fasy → fast can be matched when suitable indexed tokens exist.
Fuzzy settings
- Trigger below results: default
1. With this value the fallback runs only when normal search returns zero results. Use0to prevent the fallback from running. - Minimum token length: default
4. Shorter query tokens are excluded from fuzzy candidate matching. - Maximum edit distance: default
1. Accepted values are1or2. - Maximum candidates: default
5. Limits the number of fuzzy token candidates considered for each query token.
Security
PrismSearch validates a lightweight frontend request token and can limit search requests per server-visible IP address.
Frontend nonce protection
The frontend script sends a site-generated request token with each search request. The REST endpoint and Direct Pro endpoint reject missing or invalid tokens.
This protection is always enabled and has no user setting. It is request validation, not user authentication and not a complete bot-blocking system.
Search rate limit
Sets the maximum number of frontend searches allowed per server-visible IP address per minute. The default is 50.
The accepted range is 0 to 1000. Use 0 to disable rate limiting.
Advanced Settings
Control indexing batch size, live index maintenance and diagnostic information.
Index batch size
Controls how many objects are processed in each admin AJAX indexing batch. The default is 25, and the accepted range is 1 to 500.
Smaller batches reduce the work performed by each request. Larger batches can finish with fewer requests but require more work per request.
Live index update
Enabled by default. PrismSearch updates selected post types and selected taxonomy terms when supported save, update, quick-edit, trash or delete events run.
Normal day-to-day edits therefore do not require a complete rebuild when live updates are enabled.
REST API live updates
Disabled by default. Enable this when content created, updated or deleted through WordPress REST API requests must also trigger live index maintenance.
Index information
The Advanced panel displays the newest indexed timestamp, total index-table size, index-table count and estimated index-row count.
These values are diagnostic information reported from the PrismSearch tables and the database engine.
Pro registration Pro
Enter the registration number under Settings → PrismSearch → Registration. A valid registration enables Pro settings and licence-based updates.
If a previously registered licence expires, Pro features remain active on that site, while licence-protected updates remain unavailable until renewal.
Shortcode Reference
Add the live search box anywhere using the [prismsearch] shortcode.
Basic usage
[prismsearch]All attributes
[prismsearch min_chars="2" limit="8" placeholder="Search..." enter_redirect="1"]| Attribute | Default | Description |
|---|---|---|
min_chars | Global setting; 2 on a new install | Minimum typed characters before a request is sent. Effective range: 1–10. |
limit | Global setting; 8 on a new install | Maximum live results returned. Accepted range: 1–20. |
placeholder | Search... | Placeholder and accessible label for the search input. |
enter_redirect | Global setting | Truthy values such as 1, true, yes or on enable Enter-key redirection. Other values disable it. |
Building & Rebuilding the Index
PrismSearch uses its own index tables. Build the index after installation and rebuild it when settings that change indexed content or language processing are modified.
When to build the index
- After first installing and configuring PrismSearch
- After changing selected post types or taxonomies
- After changing the NLP language
- After adding or removing Pro searchable meta keys
- After enabling multilingual support or changing indexed languages
- After bulk imports or migrations that did not trigger live index updates
Automatic updates
With Live index update enabled, PrismSearch maintains individual selected posts and taxonomy terms during supported WordPress save, update, trash and delete events.
Enable REST API live updates when those events must also run during REST API content changes.
Clear index
The Clear Index button removes PrismSearch indexed data. Search returns no indexed results until the index is built again.
Index progress
The admin screen builds the index through consecutive AJAX batches and shows the current progress. Keep the browser tab open until the process completes.
Build duration depends on content volume, content size, selected taxonomies, searchable metadata, the configured batch size, database performance and server resources.
Template Override
Copy PrismSearch template files into your active theme or child theme to change the live result markup.
How it works
Create a template/prismsearch/ directory inside the active theme. PrismSearch checks the child theme first, then the parent theme and finally the plugin templates.
your-theme/
└── template/
└── prismsearch/
├── item.php ← one live result item
├── blocks.php ← frontend metadata and optional Pro slots
├── empty.php ← no-results message
└── show-all.php ← link to the full search page$item['id'] or $item['meta'] are not available.Available placeholders
| Placeholder | Template | Description |
|---|---|---|
__URL__ | item.php | Escaped post permalink or taxonomy-term archive URL |
__TITLE_HTML__ | item.php | Escaped title with search-term highlighting markup |
__TITLE_ATTR__ | item.php | Escaped plain title suitable for an HTML attribute |
__EXCERPT_HTML__ | item.php | Escaped excerpt with highlighting markup |
__FEATURED_IMAGE__ | item.php | Escaped featured-image URL; the default image wrapper is removed when no image is available |
__BLOCKS_HTML__ | blocks.php | Rendered frontend meta fields selected in settings |
__ADD_TO_CART_HTML__ | item.php or blocks.php | Pro WooCommerce add-to-cart markup when the placeholder is included |
__SEARCH_URL__ | show-all.php | Full WordPress search URL for the current query |
Minimal item.php example
<?php
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
?>
<div class="prismsearch-item">
<a class="prismsearch-item-title" href="__URL__" title="__TITLE_ATTR__">
__TITLE_HTML__
</a>
<span class="prismsearch-item-excerpt">__EXCERPT_HTML__</span>
<span class="prismsearch-item-blocks">__BLOCKS_HTML__</span>
</div>Template output is sanitised against PrismSearch’s allowed HTML-element and attribute list before it is embedded in the page.
Hooks & Filters
PrismSearch exposes WordPress hooks during settings, indexing, normal frontend rendering and REST search. The optional Direct Pro endpoint uses SHORTINIT, so normal theme and plugin bootstrap callbacks are not guaranteed to run inside that request.
Core filters
| Filter | Arguments | Description |
|---|---|---|
prismsearch_load_frontend_css | $load, $settings | Enable or disable the default frontend stylesheet. |
prismsearch_shortcode_defaults | $defaults | Change shortcode defaults before shortcode attributes are applied. |
prismsearch_frontend_search_url | $url | Change the frontend search-request URL. |
prismsearch_frontend_i18n | $strings | Add or change strings passed to the frontend script. |
prismsearch_frontend_meta_labels | $labels | Add the meta-key-to-label map passed to the frontend script. |
prismsearch_meta_label | $label, $key | Modify each label already present in the frontend meta-label map. |
prismsearch_frontend_meta | $meta, $post_ids, $meta_keys, $settings, $wpdb | Modify frontend metadata after values have been loaded for result posts. |
prismsearch_enabled_frontend_meta_keys | $meta_keys, $settings | Modify the frontend meta keys used by search responses. |
prismsearch_index_post_title | $title, $post | Modify a post title before tokenisation and indexing. |
prismsearch_index_post_content | $content, $post | Modify the searchable post-content string before tokenisation and indexing. |
prismsearch_supported_post_types | $post_types, $settings | Modify the discovered list of supported public post types. |
prismsearch_reindex_on_object_terms_set | $should_reindex, $object_id, $terms, $tt_ids, $taxonomy, $append, $old_tt_ids | Decide whether changing an object’s terms should reindex that post. |
prismsearch_detected_languages | $languages | Add language-code and label pairs backed by the generic processor. |
prismsearch_normalized_settings | $settings, $saved | Modify normalised core settings. |
prismsearch_sanitized_settings | $output, $input, $old, $available_languages | Modify core settings during admin form sanitisation. |
prismsearch_indexer_service | $indexer, $wpdb, $settings | Replace or extend the indexing service. |
prismsearch_search_service | $service, $wpdb, $settings | Replace or extend the search service. |
Pro filters
| Filter | Arguments | Description |
|---|---|---|
prismsearch_enabled_searchable_meta_keys | $meta_keys, $settings | Modify the Pro meta keys added to the searchable index. |
prismsearch_index_post_meta_text | $meta_text, $post_id, $post, $settings | Modify the combined searchable metadata text before Pro indexing. |
prismsearch_enabled_languages | $languages, $settings | Modify the languages enabled for Pro indexing. |
prismsearch_search_language | $language, $settings | Modify the language used for frontend result filtering. |
prismsearch_object_language | $language, $object_type, $object_id, $object_subtype, $settings | Resolve or replace the language stored for an indexed object or term. |
prismsearch_current_language_raw | $language | Provide a raw current-language value before fallback processing. |
prismsearch_post_index_url | $url, $post_id, $language, $settings | Modify the URL stored for a Pro-indexed post. |
prismsearch_frontend_price_format | $price_format | Modify WooCommerce-style price-format data passed to the Pro frontend script. |
Actions
| Action | Arguments | Description |
|---|---|---|
prismsearch_before_index_post | $post_id | Runs before a post is indexed. |
prismsearch_after_index_post | $post_id | Runs after a post has been indexed. |
prismsearch_before_build_index | None | Runs before a complete admin index build starts. |
prismsearch_after_build_index | None | Runs after a complete admin index build finishes. |
prismsearch_after_hero | None | Outputs integration content after the PrismSearch admin hero. |
prismsearch_settings_tabs | $settings | Allows integrations to output additional settings-tab buttons. |
prismsearch_settings_content_fields | $settings, $option_key, $post_type_choices, $taxonomy_choices | Allows integrations to output fields in the Content panel. |
prismsearch_settings_panels | $settings, $option_key | Allows integrations to output additional settings panels. |
Example: add custom text before indexing
add_filter( 'prismsearch_index_post_content', function( $content, $post ) {
if ( $post instanceof WP_Post && $post->post_type === 'event' ) {
$content .= ' event calendar';
}
return $content;
}, 10, 2 );Rebuild the index after adding or changing indexing filters so existing content is processed again.
Example: change shortcode defaults
add_filter( 'prismsearch_shortcode_defaults', function( $defaults ) {
$defaults['limit'] = '12';
$defaults['placeholder'] = 'Search products...';
return $defaults;
} );Translating Meta Names
PrismSearch automatically converts unknown keys such as custom_brand into readable fallback labels such as “Custom Brand”. Use the frontend label filters when a specific translated label is required.
Add labels for custom meta keys
add_filter( 'prismsearch_frontend_meta_labels', function( $labels ) {
$labels['custom_brand'] = __( 'Brand', 'your-textdomain' );
$labels['product_model'] = __( 'Model', 'your-textdomain' );
$labels['ean_code'] = __( 'EAN', 'your-textdomain' );
return $labels;
} );Modify an existing label
The prismsearch_meta_label filter runs for labels already present in the frontend label map. WooCommerce Pro adds labels for _price, _regular_price, _sale_price and _sku.
add_filter( 'prismsearch_meta_label', function( $label, $key ) {
if ( $key === '_sku' ) {
return __( 'Product code', 'your-textdomain' );
}
return $label;
}, 10, 2 );Plugin translation files
PrismSearch uses the prismsearch text domain. Standard WordPress translation tools can scan the plugin source and generate a translation catalogue.
Compiled translation files can be stored in wp-content/languages/plugins/ using the normal plugin naming convention:
prismsearch-de_DE.po
prismsearch-de_DE.mo
prismsearch-fr_FR.po
prismsearch-fr_FR.moAdd to Cart Button in Results
With registered PrismSearch Pro and WooCommerce available, include the __ADD_TO_CART_HTML__ placeholder in a template override to render the Pro add-to-cart link for product results.
Step 1 — Override blocks.php
Create template/prismsearch/blocks.php in your active theme or child theme:
<?php
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
?>
<span class="prismsearch-item-blocks">__BLOCKS_HTML__</span>
<span class="prismsearch-item-cart">__ADD_TO_CART_HTML__</span>The placeholder is replaced in the browser. Do not call wc_get_product() or expect per-result PHP variables inside the template.
Step 2 — Style the generated link
The generated anchor includes the prismsearch-add-to-cart, add_to_cart_button and ajax_add_to_cart classes.
.prismsearch-item-cart {
display: block;
margin-top: .35rem;
}
.prismsearch-add-to-cart {
display: inline-flex;
align-items: center;
justify-content: center;
padding: .35rem .8rem;
border-radius: 6px;
background: #2d60f0;
color: #fff;
font-size: .78rem;
font-weight: 600;
text-decoration: none;
}
.prismsearch-add-to-cart:hover {
background: #4d7cf4;
color: #fff;
}Step 3 — Understand the current product limitation
The current Pro frontend generates simple-product AJAX add-to-cart markup for indexed WooCommerce product results. It does not inspect the product type, stock state or purchasability before generating the link.
WooCommerce’s frontend AJAX add-to-cart script must also be available on the page for AJAX cart behaviour.
Still have questions?
Check the FAQ on the homepage or reach out via the support forum on WordPress.org.