Building Search UI

This section assumes you already indexed your content into Algolia. If you didn’t, please refer to the earlier sections.

To build a search UI in your WordPress website, it’s recommended to use the Algolia InstantSearch library. It comes in several flavors:

• InstantSearch.js
• React InstantSearch
• Vue InstantSearch
• Angular InstantSearch

This guide documents usage with InstantSearch.js, but feel free to pick a different flavor if you’re using a UI library in your theme.

Include InstantSearch in your theme

First, download the latest versions of instantsearch.production.min.js and algoliasearch-lite.umd.js and save them in your theme, under the themes/your_theme/js/vendor/ directory.

Then, register both assets in your theme’s functions.php file.

1
2
3
4
5
6
7
8
9
10
11
12
function algolia_load_assets() {
    $clientPath = '/js/vendor/algoliasearch-lite.umd.js';
    $instantSearchPath = '/js/vendor/instantsearch.production.min.js';

    // Create a version number based on the last time the file was modified
    $clientVersion = date("ymd-Gis", filemtime( get_template_directory() . $clientPath));
    $instantSearchVersion = date("ymd-Gis", filemtime( get_template_directory() . $instantSearchPath));

    wp_enqueue_script('algolia-client', get_template_directory_uri() . $clientPath, array(), $clientVersion, true);
    wp_enqueue_script('algolia-instant-search', get_template_directory_uri() . $instantSearchPath, array('algolia-client'), $instantSearchVersion, true);
}
add_action('wp_enqueue_scripts', 'algolia_load_assets');

Build the search UI

Using InstantSearch’s default CSS

InstantSearch.js provides a starter CSS template. You probably don’t need it in production, but it can be helpful during development.

You can download the latest version of the satellite-min.css file and enqueue it in your theme by adding it at the end of the algolia_load_assets function.

1
wp_enqueue_style('algolia-theme', get_template_directory_uri() . '/satellite-min.css');

You don’t have to specify a version number since this file shouldn’t make it to production.

Adding HTML containers

You can start by adding a search box in the header of your theme, by adding the following HTML code:

1
<div id="searchbox"></div>

You also need to add a list of hits and tags list where you want to display search results.

1
2
<div id="hits"></div>
<div id="tags-list"></div>

Setting up InstantSearch

First, you can create a new js/algolia-search.js file in your theme, and require it in the algolia_load_assets function.

1
2
3
4
5
6
7
function algolia_load_assets() {
    // ...

    $algoliaPath = '/js/algolia-search.js';
    $algoliaVersion = date("ymd-Gis", filemtime(get_template_directory() . $algoliaPath));
    wp_enqueue_script('algolia-search', get_template_directory_uri() . $algoliaPath, array('algolia-instant-search'), $algoliaVersion, true);
}

The following example assumes that the records in your Algolia index contain title, content and tags attributes. All attributes should be searchable, and tags should be set in attributesForFaceting.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

const search = instantsearch({
  indexName: "YourIndexName",
  searchClient,
  searchFunction(helper) {
    // Ensure we only trigger a search when there's a query
    if (helper.state.query) {
      helper.search();
    }
  },
});

search.addWidgets([
  instantsearch.widgets.searchBox({
    container: "#searchbox",
  }),

  instantsearch.widgets.refinementList({
    container: "#tags-list",
    attribute: "tags",
    limit: 5,
    showMore: true,
  }),

  instantsearch.widgets.hits({
    container: "#hits",
    templates: {
      item: `
      <article>
        <a href="{{ url }}">
          <strong>
            {{#helpers.highlight}}
              { "attribute": "title", "highlightedTagName": "mark" }
            {{/helpers.highlight}}
          </strong>
        </a>
        {{#content}}
          <p>{{#helpers.snippet}}{ "attribute": "content", "highlightedTagName": "mark" }{{/helpers.snippet}}</p>
        {{/content}}
      </article>
    `,
    },
  }),
]);

search.start();