Icon searching white

Highlighting / Snippetting

Last updated 12 October 2017

Highlighting Overview

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

Highlighting is enabled for all attributes for default and unless specified otherwise in the index settings.

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

index.setSettings({
  attributesToHighlight: [
    'content',
    'description'
  ]
});

Response Information

To provide you both the highlighted data and the original attribute value, the Algolia response will include a _highlightResult attribute, which will contain the value with highlighting, the match level (how much of the query words were matched), and the matched words for each attribute. This is seen as follows:

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

Sanitization

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.

Configuration

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.

Pre- and Post-Tags

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.

index.setSettings({
  attributesToHighlight: [
    'content',
    'description'
  ],
  highlightPreTag: '<em class="search-highlight">'
});

Snippeting Overview

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:

index.setSettings({
  attributesToSnippet: [
    'content:80',
    'description'
  ]
});

Response Information

Sanitization

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.

Configuration

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:

index.setSettings({
  attributesToSnippet: [
    'body:20',
    'title'
  ]
});

With nbWords set to 6:

"As Gregor Samsa awoke one morning…"

And nbWords set to 10:

"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:

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

UI Recommendations

Highlighting Styles

To highlight matching words, we recommend using a style that stands up from normal, non-highlighted text. Some popular options include:

  • Giving the text a different background color from the rest
  • Underlining the highlighted text

It is not recommended to apply any styles that change the size of the text. In an as-you-type search experience, the amount of text that is highlighted will be changed on each key stroke. A style that adjusts the size of the text will create a “jumpy” appearance to the text, making for a distracting and less-than-fluid experience.

Given the example query ‘pear’, here’s what some example styles of matching results could look like:

Black Pear Tree

Pearly White

Snippeting Ellipsis

Adding ellipses or some other indicator to snippeted text provides an indication to the searcher that there is more text to see. This is why we recommend leaving the default snippetEllipsisText or setting it to something that makes it clear that text otherwise exists in the removed space.

What’s Next

Continue building your Algolia knowledge with these concepts:

© Algolia - Privacy Policy