Customize your search page

Learn how to customize the WordPress search page.

---

Reminder: You should never directly edit the plugin files because all your changes would be lost at every plugin update.

---

Introduction

The instant search results experience can be enabled in the Search page section of the plugin.

The instant search results page is powered by instantsearch.js, a JavaScript library that eases the process of building rich search experiences.

Please checkout the official documentation of the instantsearch.js website. Also take a look at some examples of what can be achieved with instantsearch.js.

The Instantsearch feature will do its search on the Searchable posts index. If you don't have that index flagged for indexing, you will be invited to index it with a notice on every page of the WordPress admin.

---

Before making changes, be sure that you understand how the instantsearch.js library works. For more information, please look at their official documentations.

---

Customization

To start customizing your search results page, copy/paste the wp-content/plugins/algolia/templates directory in your own theme, and rename it to algolia. If your theme is named mytheme, then the folder should be located at wp-content/themes/mytheme/algolia.

You can then edit the algolia/instantsearch.php file to customize the instant search results page (search widgets & page layout).

---

All instantsearch.js templates are using the underscore templating. Learn more in the complete underscore templates documentation.

Edit the page layout

The instant search results page is provided with a default layout. You'll need to slightly customize it to fit your theme's look & feel. To configure the layout, edit the algolia/instantsearch.php file and locate the <div id="ais-wrapper">...</div> code:

<div id="ais-wrapper">
  <main id="ais-main">
    <div class="algolia-search-box-wrapper">
      <div id="algolia-search-box"></div>
      <svg class="search-icon" width="25" height="25" viewBox="0 0 40 40" xmlns="http://www.w3.org/2000/svg"><path d="M24.828 31.657a16.76 16.76 0 0 1-7.992 2.015C7.538 33.672 0 26.134 0 16.836 0 7.538 7.538 0 16.836 0c9.298 0 16.836 7.538 16.836 16.836 0 3.22-.905 6.23-2.475 8.79.288.18.56.395.81.645l5.985 5.986A4.54 4.54 0 0 1 38 38.673a4.535 4.535 0 0 1-6.417-.007l-5.986-5.986a4.545 4.545 0 0 1-.77-1.023zm-7.992-4.046c5.95 0 10.775-4.823 10.775-10.774 0-5.95-4.823-10.775-10.774-10.775-5.95 0-10.775 4.825-10.775 10.776 0 5.95 4.825 10.775 10.776 10.775z" fill-rule="evenodd"></path></svg>
      <div id="algolia-stats"></div>
      <div id="algolia-powered-by"></div>
    </div>
    <div id="algolia-hits"></div>
    <div id="algolia-pagination"></div>
  </main>
  <aside id="ais-facets">
    <div>
      <h3 class="widgettitle"><?php esc_html_e( 'Post Types', 'wp-search-with-algolia' ); ?></h3>
      <section class="ais-facets" id="facet-post-types"></section>
    </div>
    <div>
      <h3 class="widgettitle"><?php esc_html_e( 'Categories', 'wp-search-with-algolia' ); ?></h3>
      <section class="ais-facets" id="facet-categories"></section>
    </div>
    <div>
      <h3 class="widgettitle"><?php esc_html_e( 'Tags', 'wp-search-with-algolia' ); ?></h3>
      <section class="ais-facets" id="facet-tags"></section>
    </div>
    <div>
      <h3 class="widgettitle"><?php esc_html_e( 'Users', 'wp-search-with-algolia' ); ?></h3>
      <section class="ais-facets" id="facet-users"></section>
    </div>
  </aside>
</div>

Edit this HTML layout to change the way the overall page is structured.

Edit the hit template

Each matching Searchable Post will be rendered with a default hit template. To customize it, edit the algolia/instantsearch.php file and locate the tmpl-instantsearch-hit template:

<script type="text/html" id="tmpl-instantsearch-hit">
  <article itemtype="http://schema.org/Article">
    <# if ( data.images.thumbnail ) { #>
      <div class="ais-hits--thumbnail">
        <a href="{{ data.permalink }}" title="{{ data.post_title }}" class="ais-hits--thumbnail-link">
          <img src="{{ data.images.thumbnail.url }}" alt="{{ data.post_title }}" title="{{ data.post_title }}" itemprop="image" />
        </a>
      </div>
    <# } #>

    <div class="ais-hits--content">
      <h2 itemprop="name headline"><a href="{{ data.permalink }}" title="{{ data.post_title }}" class="ais-hits--title-link" itemprop="url">{{{ data._highlightResult.post_title.value }}}</a></h2>
      <div class="excerpt">
        <p>
          <# if ( data._snippetResult['content'] ) { #>
            <span class="suggestion-post-content ais-hits--content-snippet">{{{ data._snippetResult['content'].value }}}</span>
          <# } #>
        </p>
      </div>
    </div>
    <div class="ais-clearfix"></div>
  </article>
</script>

Adding an extra search widget

To add an extra search widget, it is best is to follow the official documentation of instantsearch.js and instantiate the widget in the algolia/instantsearch.php file, just before the Search.start() call.

// new widgets
search.addWidgets(/* ... */);

search.start();

Look & feel

We provide some default CSS rules that are located in the wp-search-with-algolia/css/algolia-instantsearch.css. You can add your own CSS rules to your theme's stylesheet.

If for any reason you don't want the default stylesheet to be included, you can remove it like this:

<?php

/**
 * Dequeue default CSS files.
 *
 * Hooked to the wp_enqueue_scripts action, with a late priority (100),
 * so that it is after the stylesheets were enqueued.
 */
function my_theme_dequeue_styles() {
  // Remove the algolia-instantsearch.css.
  wp_dequeue_style( 'algolia-instantsearch' );
}
add_action( 'wp_enqueue_scripts', 'my_theme_dequeue_styles', 100 );