Building Search

In this section, we’re assuming you already indexed your content. If you didn’t, please refer to the previous sections.

In the following parts, we’ll be building search with InstantSearch.js, a library built by Algolia to help you get the most out of your search. It comes in many versions:

• Vanilla JavaScript
• React.js
• Vue.js
• Angular.js

The documentation uses the pure JavaScript version, but feel free to pick your favorite flavor.

Include InstantSearch libraries

First, download the latest version of instantsearch.production.min.js from this page as well as algoliasearchLite.min.js from this page.

Save the files in your theme. For this documentation, we’re going to store them in a themes/your_theme/js/vendor/ folder.

Then, your theme’s functions.php register the js files. We register them to be loaded in the footer of the theme. Note that we are specifying that InstantSearch must be loaded after the Algolia client via the third parameter of wp_enqueue_script.

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

    // create version number based for the last time the file was modified
    $clientVersion  = date("ymd-Gis", filemtime( get_template_directory() . $clientPath ));
    $isVersion  = date("ymd-Gis", filemtime( get_template_directory() . $isPath ));

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

InstantSearch Example

The following section is an example built with TwentyNineteen theme, the most recent WordPress default theme.

Importing Algolia default CSS

In your final implementation, this file shouldn’t be loaded. This will only make your development process easier by applying some default style to our search.

We’ll add it the same way we added the javascript file, download the algolia-min.css file from this page, and add this line at the end of the algolia_load_assets function.

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

We don’t bother with the version number because this file generally shouldn’t make it to production.

Adding HTML containers

In this example, I’m going to add a search bar in the header but it can live anywhere in the page.

In the header.php file, inside the <header> tags, add a new tag

1
2
<aside id="searchbox"></aside>
<aside id="tags-list"></aside>

For the results, we’re going to use the #content tag, to make a full page results list.

Setting up InstantSearch

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() {
    // Previous code, hidden for brevity

    $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 );
}

Now, head to your dashboard, under the API Key tab, grab the search-only API key.

You must use a search-only API key, do not ever use the admin API key, otherwise anybody would be able to use your Algolia account.

All the instant search code will live in this new file. The following snippet will:

• Instantiate Algolia with Search-only API key
• Hook the search box
• Add tag filters
• Define where to show the result
• Create a template used to display each results

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
48
49
50
51
52
const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

const search = instantsearch({
  indexName: "YOUR_INDEX_NAME",
  searchClient,
  searchFunction(helper) {
    if (helper.state.query) {
      helper.search();
    }
  },
});

search.addWidget(
  instantsearch.widgets.searchBox({
    container: '#searchbox',
    limit: 5,
    showMore: true,
  })
);

// This requires `tags` to be set in the `attributesForFacetings`
// in your Algolia index settings
search.addWidget(
  instantsearch.widgets.refinementList({
    container: '#tags-list',
    attribute: 'tags',
  })
);

search.addWidget(
  instantsearch.widgets.hits({
    container: '#content',
    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();

If you want to previous snippet to display properly, your Algolia index must have these settings:

1
2
3
4
5
{
  "attributesForFaceting": ["title"],
  "attributesToSnippet": ["title", "content"],
  "attributesForFaceting": ["tags"]
}