Highlighting / 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.

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 will not 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 are stored in the engine. For this reason, there is no sanitization and all such actions should be taken on the 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- and post-tags. This configuration provides the flexibility to leverage any tag (HTML or otherwise) to highlight results in the UI.

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

The settings can be configured utilizing 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>'
});

Note These settings are normally used together.

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- and post-highlighting tags.

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

The number of words to be returned within the snippet can be set using the nbWords parameter. This is set when defining attributesToSnippet with a syntax of attribute:nbWords. When not defined, 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 this setting can be changed with the snippetEllipsisText setting:

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

Please note that 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 returns snippeted results as they are stored in the engine with HTML removed, as otherwise we cannot ensure that matching tags will both be within the returned snippet.