Guides / Building Search UI / UI & UX patterns

Highlighting and Snippeting

Highlighting

Highlighting is an important tool to demonstrate to searchers why a result matched their query by providing different styling to all matched query words.

By default, Highlighting is enabled on all searchableAttributes unless specified otherwise in attributesToHighlight.

Use an API client, not InstantSearch, to configure attributesToHighlight.

Below is an example of how to configure which attributes to highlight:

1
2
3
4
5
6
index.setSettings({
  attributesToHighlight: [
    'content',
    'description'
  ]
});

If exactOnSingleWordQuery is set to word, only exact matches will be highlighted: partials and prefixes won’t be.

Response information

The Algolia response will include a _highlightResult for each attribute, which will contain the attribute’s value with highlighting, the match level (how much of the query words were matched), a boolean indicating if the whole attribute is highlighted, and the matched words for each attribute. This is seen as follows:

1
2
3
4
5
6
{
    "value":"<em>Action</em>tec - 4-Port Ethernet Broadband Router with Wireless-N - Black",
    "matchLevel":"full",
    "fullyHighlighted":false,
    "matchedWords":["action"]
}

Sanitization of the results

Algolia returns highlighted results as they’re stored in the engine. That’s why sanitation and similar tasks need to be handled client-side. Not doing so, particularly with user-provided content, can be a security risk.

Pre- and post-tags

The primary configuration that can be set for highlighting are the pre-tags and post-tags. This configuration provides the flexibility to leverage any tag (HTML or otherwise) to highlight results in the UI.

The pre-tags and post-tags (that is, the strings that are before and after the matched query words) can be set to any string. They’re set to <em> and </em> by default.

You can configure this setting using the highlightPreTag and highlightPostTag parameters at either query or indexing time.

1
2
3
4
5
6
7
8
index.setSettings({
  attributesToHighlight: [
    'content',
    'description'
  ],
  highlightPreTag: '<em class="search-highlight">',
  highlightPostTag: '</em>'
});

These settings are normally used together.

Highlighting using InstantSearch

Algolia provides a highlight widget in the InstantSearch libraries to highlight matches on the front end. Refer to the widget docs for usage notes and code examples.

Snippeting

Snippeting will return only a portion of the matched attribute; namely, the matched words and some words around them. Unlike highlighting, snippeting must be proactively enabled for each attribute you wish to snippet, although you can set the value * to snippet all attributes.

The snippeted result will wrap matched words in the pre-highlighting and post-highlighting tags.

Use an API client, not InstantSearch, to configure attributesToSnippet.

An example configuration of the attributesToSnippet:

1
2
3
4
5
6
index.setSettings({
  attributesToSnippet: [
    'content:80',
    'description'
  ]
});

Snippeted results can be configured, particularly with regards to which attributes, how many words in the returned results, and which text will replace removed words in the snippet.

nbWords

You can set the number of words to return when defining your attributesToSnippet with the syntax attribute:nbWords. For example, body:20 returns twenty-word snippets for the attribute body. When undefined, the value defaults to 10.

1
2
3
4
5
6
index.setSettings({
  attributesToSnippet: [
    'body:20',
    'title'
  ]
});

With nbWords set to 6:

1
"As Gregor Samsa awoke one morning …"

And nbWords set to 10:

1
"As Gregor Samsa awoke one morning from uneasy dreams he …"

Ellipsis text

To denote that words have been removed from the snippeted text, the engine will insert text in its place.

The default replacement text is (U+20216). However, you can change this with the snippetEllipsisText setting:

1
2
3
index.setSettings({
  snippetEllipsisText: '[&hellip;]'
});

An additional space (U+0020 Unicode character) is added after the start and before the ending of the ellipsis. For example:

1
"… awoke one morning …"

Sanitization of the results

Algolia removes valid HTML tags from the snippeted results to ensure you can add the matching tags. However, if you store invalid HTML, browsers can still interpret it. Therefore, please make sure to safely display this data, especially if your records contain user-generated content. Unsanitized HTML content opens up the possibility of Cross-site-scripting attacks on your site.

Snippeting using InstantSearch

There’s a snippet widget in the InstantSearch libraries to snippet text attributes on the front end. Please refer to the widget docs for usage notes and code examples.

Did you find this page helpful?