Highlighting in InstantSearch.js

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 one of the API clients or the Algolia dashboard, not InstantSearch, to configureattributesToHighlight.

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

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings
  {
    AttributesToHighlight = new List<string> { "author", "title", "content" },
  }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    attributesToHighlight: [
      "author",
      "title",
      "content",
    ],
  ),
);

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "INDEX_NAME",
  search.NewEmptyIndexSettings().SetAttributesToHighlight(
    []string{"author", "title", "content"})))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.setSettings(
  "INDEX_NAME",
  new IndexSettings().setAttributesToHighlight(Arrays.asList("author", "title", "content"))
);

const response = await client.setSettings({
  indexName: 'theIndexName',
  indexSettings: { attributesToHighlight: ['author', 'title', 'content'] },
});

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(attributesToHighlight = listOf("author", "title", "content")),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['attributesToHighlight' => [
        'author',

        'title',

        'content',
    ],
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "attributesToHighlight": [
            "author",
            "title",
            "content",
        ],
    },
)

response = client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(attributes_to_highlight: ["author", "title", "content"])
)

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      attributesToHighlight = Some(Seq("author", "title", "content"))
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(attributesToHighlight: ["author", "title", "content"])
)

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:

JSON

{
  "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.

Sanitize 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 lets you use 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.

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings
  {
    AttributesToHighlight = new List<string> { "author", "title", "content" },
    HighlightPreTag = "<em class=\"search-highlight\">",
    HighlightPostTag = "</em>",
  }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    attributesToHighlight: [
      "author",
      "title",
      "content",
    ],
    highlightPreTag: "<em class=\"search-highlight\">",
    highlightPostTag: "</em>",
  ),
);

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "INDEX_NAME",
  search.NewEmptyIndexSettings().SetAttributesToHighlight(
    []string{"author", "title", "content"}).SetHighlightPreTag("<em class=\"search-highlight\">").SetHighlightPostTag("</em>")))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.setSettings(
  "INDEX_NAME",
  new IndexSettings()
    .setAttributesToHighlight(Arrays.asList("author", "title", "content"))
    .setHighlightPreTag("<em class=\"search-highlight\">")
    .setHighlightPostTag("</em>")
);

const response = await client.setSettings({
  indexName: 'theIndexName',
  indexSettings: {
    attributesToHighlight: ['author', 'title', 'content'],
    highlightPreTag: '<em class="search-highlight">',
    highlightPostTag: '</em>',
  },
});

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings =
      IndexSettings(
        attributesToHighlight = listOf("author", "title", "content"),
        highlightPreTag = "<em class=\"search-highlight\">",
        highlightPostTag = "</em>",
      ),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['attributesToHighlight' => [
        'author',

        'title',

        'content',
    ],
        'highlightPreTag' => '<em class="search-highlight">',
        'highlightPostTag' => '</em>',
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "attributesToHighlight": [
            "author",
            "title",
            "content",
        ],
        "highlightPreTag": '<em class="search-highlight">',
        "highlightPostTag": "</em>",
    },
)

response = client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(
    attributes_to_highlight: ["author", "title", "content"],
    highlight_pre_tag: "<em class=\"search-highlight\">",
    highlight_post_tag: "</em>"
  )
)

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      attributesToHighlight = Some(Seq("author", "title", "content")),
      highlightPreTag = Some("<em class=\"search-highlight\">"),
      highlightPostTag = Some("</em>")
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(
        attributesToHighlight: ["author", "title", "content"],
        highlightPreTag: "<em class=\"search-highlight\">",
        highlightPostTag: "</em>"
    )
)

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

Highlighting using InstantSearch

Algolia provides a Highlight 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 one of the API clients or the Algolia dashboard, not InstantSearch, to configureattributesToSnippet.

An example configuration of the attributesToSnippet:

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings
  {
    AttributesToSnippet = new List<string> { "content:80", "description" },
  }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    attributesToSnippet: [
      "content:80",
      "description",
    ],
  ),
);

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "INDEX_NAME",
  search.NewEmptyIndexSettings().SetAttributesToSnippet(
    []string{"content:80", "description"})))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.setSettings(
  "INDEX_NAME",
  new IndexSettings().setAttributesToSnippet(Arrays.asList("content:80", "description"))
);

const response = await client.setSettings({
  indexName: 'theIndexName',
  indexSettings: { attributesToSnippet: ['content:80', 'description'] },
});

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(attributesToSnippet = listOf("content:80", "description")),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['attributesToSnippet' => [
        'content:80',

        'description',
    ],
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "attributesToSnippet": [
            "content:80",
            "description",
        ],
    },
)

response = client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(attributes_to_snippet: ["content:80", "description"])
)

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      attributesToSnippet = Some(Seq("content:80", "description"))
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(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).

Number of words

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.

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings
  {
    AttributesToSnippet = new List<string> { "body:20", "title" },
  }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    attributesToSnippet: [
      "body:20",
      "title",
    ],
  ),
);

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "INDEX_NAME",
  search.NewEmptyIndexSettings().SetAttributesToSnippet(
    []string{"body:20", "title"})))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.setSettings(
  "INDEX_NAME",
  new IndexSettings().setAttributesToSnippet(Arrays.asList("body:20", "title"))
);

const response = await client.setSettings({
  indexName: 'theIndexName',
  indexSettings: { attributesToSnippet: ['body:20', 'title'] },
});

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(attributesToSnippet = listOf("body:20", "title")),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['attributesToSnippet' => [
        'body:20',

        'title',
    ],
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "attributesToSnippet": [
            "body:20",
            "title",
        ],
    },
)

response = client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(attributes_to_snippet: ["body:20", "title"])
)

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      attributesToSnippet = Some(Seq("body:20", "title"))
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(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

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:

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings { SnippetEllipsisText = "[&hellip;]" }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    snippetEllipsisText: "[&hellip;]",
  ),
);

response, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "INDEX_NAME",
  search.NewEmptyIndexSettings().SetSnippetEllipsisText("[&hellip;]")))
if err != nil {
  // handle the eventual error
  panic(err)
}

UpdatedAtResponse response = client.setSettings("INDEX_NAME", new IndexSettings().setSnippetEllipsisText("[&hellip;]"));

const response = await client.setSettings({
  indexName: 'theIndexName',
  indexSettings: { snippetEllipsisText: '[&hellip;]' },
});

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(snippetEllipsisText = "[&hellip;]"),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['snippetEllipsisText' => '[&hellip;]',
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "snippetEllipsisText": "[&hellip;]",
    },
)

response = client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(snippet_ellipsis_text: "[&hellip;]")
)

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      snippetEllipsisText = Some("[&hellip;]")
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(snippetEllipsisText: "[&hellip;]")
)

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

"… awoke one morning … "

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

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.
HTML splitter code

Snippeting using InstantSearch

There’s a Snippet widget in the InstantSearch libraries to snippet text attributes on the frontend. Refer to the widget docs for usage notes and code examples.

​Highlighting

​Response information

​Performance

​Sanitize the results

​Pre- and post-tags

​Highlighting using InstantSearch

​Snippeting

​Number of words

​Ellipsis text

​Sanitize the results

​An alternative to snippets

​Snippeting using InstantSearch

Highlighting

Response information

Performance

Sanitize the results

Pre- and post-tags

Highlighting using InstantSearch

Snippeting

Number of words

Ellipsis text

Sanitize the results

An alternative to snippets

Snippeting using InstantSearch