Highlighting

Visually highlights matched terms in search results.

About this widget

Displays the highlighted attributes of your search results.

With InstantSearch Android, the Highlightable interface and HighlightedString objects simplify highlighting the correct words in a search response that match your query.

See also: Get started with imperative UI

Explore example code

Examples

Consider a movies index. Each movie record consists of two fields: title and year. Algolia’s response to the query “red” could look like:

JSON

{
  "title": "The Shawshank Redemption",
  "year": 1994,
  "genre": ["action", "adventure"],
  "actors": ["Tim Robbins", "Morgan Freeman"],
  "objectID": "439817390",
  "_highlightResult": {
    "title": {
      "value": "The Shawshank <em>Red</em>emption",
      "matchLevel": "full",
      "fullyHighlighted": false,
      "matchedWords": ["red"]
    }
  }
}

To display those movies in your interface, you likely have created a data class that looks something like the following:

Kotlin

import com.algolia.instantsearch.core.Indexable

@Serializable
data class Movie(
    val title: String,
    val year: String,
    val genre: List<String>,
    override val objectID: String,
) : Indexable

Update it to add some highlighting. Implementing Highlightable will deserialize the _highlightResult for each movie, and make it available through the getHighlight{s} methods. Create @Transient attributes for each highlight to display, being either single values or lists:

Kotlin

import com.algolia.instantsearch.core.Indexable

@Serializable
data class Movie(
    val title: String,
    val year: String,
    val genre: List<String>,
    override val objectID: String,
    override val _highlightResult: JsonObject?
) : Indexable, Highlightable {

  @Transient
  public val highlightedTitle: HighlightedString?
      get() = getHighlight("title")

  @Transient
  public val highlightedGenres: List<HighlightedString>?
      get() = getHighlights("genre")

  @Transient
  public val highlightedActors: List<HighlightedString>?
      get() = getHighlights("actors")
}

Use these highlighted strings in the interface, for example in a MovieViewHolder.

Using highlighted strings in an Android view

• Directly as a SpannedString, with the highlight defaulting to bold:

  Kotlin

  TextUtils.concat(highlightedTitle?.toSpannedString(), " ($year)")
  

• As a customized SpannedString, specifying a ParcelableSpan to use as highlight style:

  Kotlin

  highlightedGenres?.toSpannedString(BackgroundColorSpan(Color.YELLOW))
      ?: buildSpannedString { italic { append("unknown genre") } }
  

• Any way you want, iterating on HighlightedString#tokens to process it however you like:

  Kotlin

  // Displays actors with highlighted parts in uppercase
  highlightedActors?.joinToString { highlight ->
      highlight.tokens.joinToString("") {
          if (it.highlighted) it.content.uppercase() else it.content
      }
  }
  

Compose UI

• Directly as a AnnotatedString, with the highlight defaulting to bold:

  Kotlin

  highlightedTitle?.toAnnotatedString()
  

• As a customized AnnotatedString, specifying a SpanStyle to use as highlight style:

  Kotlin

  highlightedGenres?.toAnnotatedString(SpanStyle(background = Color.Yellow))
      ?: AnnotatedString("unknown genre", SpanStyle(fontStyle = FontStyle.Italic))
  

• Any way you want, iterating on HighlightedString#tokens to process it however you like:

  Kotlin

  // Displays actors with highlighted parts in uppercase
  highlightedActors?.joinToString { highlight ->
      highlight.tokens.joinToString("") {
          if (it.highlighted) it.content.uppercase() else it.content
      }
  }