Highlighting

About this widget

HighlightedString simplifies highlighting the words in a search response that match your query.
You can read more about the concept of highlighting in our highlighting guide.

Examples

Lets take the example of an index containing movies. Each movie record consists of two fields: title and year. Here is what the search engine response for a query "red" could look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "title": "The Shawshank Redemption",
  "year": 1994,
  "objectID": "439817390",
  "_highlightResult": {
    "title": {
      "value": "The Shawshank <em>Red</em>emption",
      "matchLevel": "full",
      "fullyHighlighted": false,
      "matchedWords": [
        "red"
      ]
    }
  }
}

We are interested in the _highlightResult’s value: "The Shawshank <em>Red</em>emption". The part of the string to highlight is marked with <em> tags or your custom tags.

HighlightedString is constructed with a raw tagged string, detects the tags and creates a TaggedString.
This tagged string provides following properties:

• input: the input string.
• output: the input string without its tags.
• taggedRanges: a list of ranges defining highlighted ranges in output.

You can build a highlighted string in iOS is with an NSAttributedString. InstantSearch provides HighlightedString and NSAttributedString extensions to make this easy.

1
2
3
4
5
6
7
8
9
10
  let rawHighlightedString = "The Shawshank <em>Red</em>emption"
  let highlightedString = HighlightedString(string: rawHighlightedString)

  // Attributes to apply for a highlighted part of the string
  let highLightingAttributes: [NSAttributedString.Key: Any] = [
    .foregroundColor: UIColor.red
  ]

  // Create attributed string highlighted part of which is red
  let attributedString = NSAttributedString(highlightedString: highlightedString, attributes: attributes)

The produced NSAttributedString can be assigned to a UIKit component that supports it.

1
2
3
4
  let attributedString: NSAttributedString = ...
  let label: UILabel = ...

  label.attributedText = attributedString

The Hit wrapper structure uses the HighlightedString structure. You can extract a highlighted string for an attribute using its hightlightedString(forKey key: String) function.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
/* JSON search response
  {
    "title": "The Shawshank Redemption",
    "year": 1994,
    "objectID": "439817390",
    "_highlightResult": {
      "title": {
        "value": "The Shawshank <em>Red</em>emption",
        "matchLevel": "full",
        "fullyHighlighted": false,
        "matchedWords": [
          "red"
        ]
      },
    }
  }
*/

struct Movie: Codable {
  let title: String
  let year: Int
}

let movieHit: Hit<Movie> = ... /* parse JSON response */

let highlightedMovieTitle: HighlightedString? = movieHit.hightlightedString(forKey: "title")

You can read more about usage of the Hit wrapper structure in the Hits reference.