Template Overrides

CelerSearch uses a theme-overridable template system, similar to WooCommerce. You can customize any template by copying it into your theme — no plugin files need to be edited directly.

How It Works

When CelerSearch renders a template, it checks three locations in priority order:

Text

1. Child Theme   →  your-theme/celersearch/...
2. Parent Theme  →  parent-theme/celersearch/...
3. Plugin        →  plugins/celersearch/templates/...

The first file found wins. This means you can override any template by placing a copy in your child theme (or parent theme) at the matching path.

Search View Templates

Search view templates control the full search interface rendered by the [celersearch] shortcode.

Override directory

Copy templates to your theme at:

Text

your-theme/
└── celersearch/
    └── views/
        └── search/
            ├── search.php
            ├── result-item.php
            ├── no-results.php
            ├── pagination.php
            ├── facet-group.php
            └── error.php

Template reference

Template	Rendering	Description
`search/search.php`	PHP (server-side)	Main search container with input, facets, and result areas
`search/result-item.php`	JS (Mustache)	Individual search result card
`search/no-results.php`	PHP (server-side)	Message shown when no results are found
`search/pagination.php`	JS (Mustache)	Previous / next pagination controls
`search/facet-group.php`	JS (Mustache)	A group of filter facets
`search/error.php`	PHP (server-side)	Error display (admin-only)

Two rendering modes

Search templates use two different rendering modes:

PHP templates (search.php, no-results.php, error.php) run on the server and receive data via the $template_args array. You can use any PHP logic.
JS templates (result-item.php, pagination.php, facet-group.php) are loaded as strings and processed in the browser using Mustache-style {{placeholder}} syntax. They must not contain PHP logic — only static HTML with placeholders.

search.php

Rendered server-side. Available variables via $template_args:

Variable	Type	Description
`$template_args['view']`	`SearchView`	The view instance
`$template_args['config']`	`array`	View configuration (placeholder, show_facets, class, etc.)
`$template_args['unique_id']`	`string`	Unique HTML ID for this instance
`$template_args['templates']`	`array`	JS sub-templates keyed by name

result-item.php

Rendered client-side with Mustache. Available placeholders:

Placeholder	Description
`{{id}}`	Post ID
`{{title}}`	Post title (highlighted if enabled)
`{{excerpt}}`	Post excerpt (highlighted if enabled)
`{{url}}`	Permalink
`{{thumbnail}}`	Thumbnail URL (empty string if none)
`{{post_type}}`	Post type slug
`{{post_type_label}}`	Post type display label
`{{date}}`	Formatted date
`{{author}}`	Author display name

Conditional blocks:

Block	Description
`{{#thumbnail}}...{{/thumbnail}}`	Renders only if a thumbnail exists
`{{^thumbnail}}...{{/thumbnail}}`	Renders only if there is no thumbnail

no-results.php

Rendered server-side. Contains static translatable text — no variables needed. Override to change the message or add suggestions.

pagination.php

Rendered client-side with Mustache. Available placeholders:

Placeholder	Description
`{{current_page}}`	Current page number
`{{total_pages}}`	Total number of pages
`{{prev_disabled}}`	`disabled` attribute or empty string
`{{next_disabled}}`	`disabled` attribute or empty string

Rendered client-side with Mustache. Available placeholders:

Placeholder	Description
`{{label}}`	Facet group label
`{{key}}`	Facet attribute key
`{{items}}`	Pre-rendered facet items HTML

error.php

Rendered server-side. Available variables via $template_args:

Variable	Type	Description
`$template_args['errors']`	`array`	List of error message strings

Autocomplete Templates

Autocomplete templates control the search-as-you-type dropdown. All autocomplete templates are rendered client-side using Mustache-style placeholders.

Override directory

Text

your-theme/
└── celersearch/
    └── autocomplete/
        ├── container.php
        ├── suggestion.php
        ├── header.php
        ├── footer.php
        └── empty.php

Template reference

Template	Description	Default state
`container.php`	Wrapper around the dropdown	Active
`suggestion.php`	Individual suggestion item	Active
`header.php`	Top of the dropdown	Disabled (empty by default)
`footer.php`	Bottom of the dropdown	Disabled (empty by default)
`empty.php`	No-results state	Active

container.php

Placeholder	Description
`{{suggestions}}`	Rendered suggestion items
`{{query}}`	Current search query
`{{total}}`	Total number of results
`{{pagination}}`	Pagination nav when there's more than one page (empty string otherwise). If omitted from an override, the JS appends pagination after the container automatically.

suggestion.php

Placeholder	Description
`{{index}}`	Item index (0-based)
`{{id}}`	Post ID
`{{post_type}}`	Post type slug
`{{post_type_label}}`	Post type label (e.g., "Post", "Page")
`{{title}}`	Post title (highlighted if match)
`{{excerpt}}`	Post excerpt (highlighted if match)
`{{url}}`	Post permalink
`{{edit_url}}`	Admin edit URL
`{{thumbnail}}`	Thumbnail URL (may be empty)

Conditional blocks:

Block	Description
`{{#thumbnail}}...{{/thumbnail}}`	Renders if thumbnail exists
`{{^thumbnail}}...{{/thumbnail}}`	Renders if no thumbnail
`{{#show_actions}}...{{/show_actions}}`	Renders if actions are enabled
`{{#edit_url}}...{{/edit_url}}`	Renders if edit URL is available

header.php / footer.php

Placeholder	Description
`{{query}}`	Search query string
`{{total}}`	Total number of results

Both are disabled by default (the files contain commented-out examples). To enable, copy to your theme and uncomment the HTML.

empty.php

Placeholder	Description
`{{query}}`	Search query string

Override Example

Customizing the result item

Add a "Read more" button to search results:

Copy the template to your theme:

Shell

mkdir -p your-theme/celersearch/views/search
cp wp-content/plugins/celersearch/templates/views/search/result-item.php \
   wp-content/themes/your-theme/celersearch/views/search/result-item.php

Edit the theme copy to add a button:

HTML

<div class="cs-search__item" data-post-id="{{id}}">
  <a href="{{url}}" class="cs-search__item-link">
    {{#thumbnail}}
    <img class="cs-search__item-thumb" src="{{thumbnail}}" alt="" loading="lazy">
    {{/thumbnail}}
    <div class="cs-search__item-body">
      <span class="cs-search__item-type">{{post_type_label}}</span>
      <h3 class="cs-search__item-title">{{title}}</h3>
      <p class="cs-search__item-excerpt">{{excerpt}}</p>
      <div class="cs-search__item-meta">
        <span class="cs-search__item-date">{{date}}</span>
        <span class="cs-search__item-author">{{author}}</span>
      </div>
      <span class="cs-search__item-readmore">Read more &rarr;</span>
    </div>
  </a>
</div>

Copy the footer template:

Shell

mkdir -p your-theme/celersearch/autocomplete
cp wp-content/plugins/celersearch/templates/autocomplete/footer.php \
   wp-content/themes/your-theme/celersearch/autocomplete/footer.php

Replace the contents with the uncommented version:

PHP

<?php defined( 'ABSPATH' ) || exit; ?>
<div class="celersearch-autocomplete__footer">
  <a href="<?php echo esc_url( home_url( '/?s={{query}}' ) ); ?>"
     class="celersearch-autocomplete__view-all">
    <?php esc_html_e( 'View all results', 'celersearch' ); ?>
  </a>
</div>

Filter Hooks

Four filters let you modify template behavior programmatically.

celersearch_view_template_path

Modify the list of file paths checked when locating a search view template.

PHP

add_filter( 'celersearch_view_template_path', function ( array $locations, string $template ): array {
    // Add a custom location with highest priority
    array_unshift( $locations, get_stylesheet_directory() . '/custom-celersearch/' . $template . '.php' );
    return $locations;
}, 10, 2 );

celersearch_view_template_html

Filter the rendered HTML output of a search view template.

PHP

add_filter( 'celersearch_view_template_html', function ( string $html, string $template, $view ): string {
    if ( $template === 'search/search' ) {
        $html .= '<p class="cs-powered-by">Powered by CelerSearch</p>';
    }
    return $html;
}, 10, 3 );

celersearch_template_locations

Modify the list of file paths checked when locating an autocomplete template.

PHP

add_filter( 'celersearch_template_locations', function ( array $locations, string $name ): array {
    // Add a custom location with highest priority
    array_unshift( $locations, get_stylesheet_directory() . '/custom-celersearch/' . $name . '.php' );
    return $locations;
}, 10, 2 );

celersearch_js_templates

Filter or replace the autocomplete JS template strings before they are passed to JavaScript.

PHP

add_filter( 'celersearch_js_templates', function ( array $templates ): array {
    // Replace the empty-state template entirely
    $templates['empty'] = '<div class="my-custom-empty">Nothing found for "{{query}}".</div>';
    return $templates;
} );

Tips

Only override what you need. You don't have to copy every template — just the ones you want to change.
Compare overrides after plugin updates. When CelerSearch updates, check if the default templates changed and update your overrides accordingly.
Never edit plugin files directly. Changes inside wp-content/plugins/celersearch/ will be lost on the next update.
Use the filter hooks when you need a small change. A one-line tweak via celersearch_view_template_html is often simpler than a full template override.

Complete Directory Reference

All possible theme override paths:

Text

your-theme/
└── celersearch/
    ├── views/
    │   └── search/
    │       ├── search.php
    │       ├── result-item.php
    │       ├── no-results.php
    │       ├── pagination.php
    │       ├── facet-group.php
    │       └── error.php
    └── autocomplete/
        ├── container.php
        ├── suggestion.php
        ├── header.php
        ├── footer.php
        └── empty.php

What's Next?

Search Views — View configuration and shortcode usage
Autocomplete Hooks — All autocomplete filter and action hooks
Search Hooks — Search-related filter and action hooks