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.

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.

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

Note These settings are normally used together.

Highlighting using InstantSearch

We provide a highlight widget in our InstantSearch libraries to highlight matches on the front end. Please 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- 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

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: '[…]'
});

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 removes valid HTML tags from the snippeted results to ensure we 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 XSS-attacks on your site.

Snippeting using InstantSearch

We provide a snippet widget in our InstantSearch libraries to snippet text attributes on the front end. Please refer to the widget docs for usage notes and code examples.