Highlighting in Algolia for Flutter

Algolia for Flutter is beta software according to Algolia’s Terms of Service (“Beta Services”). To share feedback or report a bug, open an issue.

Highlighting

Highlighting is a vital tool for showing 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 or the Dashboard, 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: partial matches and prefixes won’t be.

Response information

The response includes a _highlightResult for each attribute, containing:

• The attribute’s value with highlighting
• The match level (how many query words matched)
• A boolean indicating if the whole attribute is highlighted
• The matched words for each attribute.

For example:

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"]
}

Performance

Algolia highlights the first 50,000 characters of the whole result set (5,000 logograms for CJK languages). This limit prevents impacting the user experience by ensuring a fast response time even with large results.

Sanitization of the results

Since Algolia returns highlighted results as they’re stored in the engine, make sure you sanitize your HTML. Unsanitized or invalid HTML content, particularly with user-provided content, can be a security risk and opens up the possibility of cross-site-scripting attacks on your site.

Pre- and post-tags

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

You can set the pre-tags and post-tags (that is, the strings before and after the matched query words) to any string value. 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>'
});

Pre-tag and post-tag settings are typically used together.

Highlighting using InstantSearch

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

Snippeting

Snippeting returns parts of the matched attribute, namely, the matched words and some words around them. Unlike highlighting, you must enable snippeting for each attribute you wish to snippet, although you can set the value * to snippet all attributes.

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

Use an API client or the dashboard, not InstantSearch, to configure attributesToSnippet.

An example configuration of the attributesToSnippet:

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

For each attribute, you can configure how snippet results are displayed by defining:

• The number of words in the resulting snippet (nbWords)
• The text used to replace removed words in the snippet (snippetEllipsisText).

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

The engine inserts text to show where words have been removed from the snippeted text.

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

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

The engine adds an extra space (Unicode U+0020) before and after snippetEllipsisText. For example:

1
"… awoke one morning … "

Sanitization of the results

Algolia removes all HTML tags from the snippeted results to ensure the text displays correctly within pre-highlighting and post-highlighting tags.

An alternative to snippets

If you want an attribute to keep its HTML formatting, instead of asking Algolia to shorten (snippet) it for you, create short-form records in your data based on a subset of the original, longer-form records. Ensure that these short-form records are restricted to an appropriate length and contain valid HTML (all opening tags have matching closing tags). You can do this programmatically, for example, with:

• HTML splitter code (like this PHP example)
• RegExp. If you have a limited, known set of HTML, you can use regular expressions to split the content. Be aware of the limitations of the RegExp approach.