API Reference / React InstantSearch / Highlight

Highlight

Signature 
<Highlight
  attribute={__string|array_}
  hit={object}
  // Optional parameters
  tagName={string}
  nonHighlightedTagName={string}
  separator={React.Node}
/>
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The Highlight widget displays highlighted attributes of your search results.

Requirements

The required hit prop is an object as provided by Hits, InfiniteHits (or their connectors). You can use this widget even with a different object than the Algolia results. The only requirement is that the provided value must have the following structure:

Copy 
1
2
3
4
5
6
7

{
  "_highlightResult": {
    "attributeName": {
      "value": "..."
    }
  }
}

Examples

Copy 
1
2
3
4
5

import { Hits, Highlight } from 'react-instantsearch-dom';

const Hit = ({ hit }) => <Highlight hit={hit} attribute="name" />;

<Hits hitComponent={Hit} />

Props

attribute
type: string
Required

The attribute of the record to highlight. You can give a dot-separated value for deeply nested objects, like actor.name.

If an attribute name contains a period (.), you can opt-out of the splitting on periods by passing the attribute path as an array, like ['actor.name', 'fr'].
Copy 
1
2
3
4

<Highlight
  // ...
  attribute="name"
/>
hit
type: object
Required

The original hit object, given from Hits or connectHits. Needs a _highlightResult[attribute].value property to work.
Copy 
1
2
3
4

<Highlight
  // ...
  hit={hit}
/>
tagName
type: string
default: "em"
Optional

The HTML tag to use for the highlighted parts of the string.

For example: mark.
Copy 
1
2
3
4

<Highlight
  // ...
  tagName="mark"
/>
nonHighlightedTagName
type: string
default: "span"
Optional

The HTML tag to use for the non-highlighted parts of the string.

For example: span.
Copy 
1
2
3
4

<Highlight
  // ...
  nonHighlightedTagName="span"
/>
separator
type: React.Node
default: ", "
Optional

The character that joins the items if the attribute to highlight is an array.
Copy 
1
2
3
4

<Highlight
  // ...
  separator=" - "
/>

HTML output

Copy 
1
2
3
4

<span class="ais-Highlight">
  <span class="ais-Highlight-nonHighlighted">This is the</span>
  <em class="ais-Highlight-highlighted">highlighted text</em>
</span>

Or with mark as the tagName:

Copy 
1
2
3
4

<span class="ais-Highlight">
  <span class="ais-Highlight-nonHighlighted">This is the</span>
  <mark class="ais-Highlight-highlighted">highlighted text</mark>
</span>

Customize the UI with connectHighlight

If you want to create your own UI of the Highlight widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

This connector is also used to build other widgets: Snippet

It’s a 3-step process:

// 1. Create a React component
const Highlight = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomHighlight = connectHighlight(Highlight);

// 3. Use your connected widget
<CustomHighlight />

See code examples

Create a React component

const Highlight = ({ function highlight }) => {
  // return the DOM output
};

Provided Props

highlight
type: function

A function to which you provide the property which contains the highlighting (always _highlightResult). It returns an array of objects, with an isHighlighted boolean property to say whether this part should be in the tag for highlighting or not, as well as a value string property.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

const Highlight = ({ highlight, attribute, hit }) => {
  const parsedHit = highlight({
    highlightProperty: '_highlightResult',
    attribute,
    hit,
  });

  return (
    <span>
      {parsedHit.map(
        (part, index) =>
          part.isHighlighted ? (
            <mark key={index}>{part.value}</mark>
          ) : (
            <span key={index}>{part.value}</span>
          )
      )}
    </span>
  );
};

Create and instantiate your connected widget

const CustomHighlight = connectHighlight(Highlight);

<CustomHighlight
  attribute={string}
  hit={object}
/>

Exposed Props

attribute
type: string
Required

The attribute of the record to highlight. You can give a dot-separated value for deeply nested objects, like actor.name.
Copy 
1
2
3
4

<CustomHighlight
  // ...
  attribute="name"
/>
hit
type: object
Required

The original hit object, given from Hits or connectHits. Needs a _highlightResult[attribute].value property to work.
Copy 
1
2
3
4

<CustomHighlight
  // ...
  hit={hit}
/>

Full example

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import { connectHighlight } from 'react-instantsearch-dom';

const Highlight = ({ highlight, attribute, hit }) => {
  const parsedHit = highlight({
    highlightProperty: '_highlightResult',
    attribute,
    hit,
  });

  return (
    <span>
      {parsedHit.map(
        (part, index) =>
          part.isHighlighted ? (
            <mark key={index}>{part.value}</mark>
          ) : (
            <span key={index}>{part.value}</span>
          )
      )}
    </span>
  );
};

const CustomHighlight = connectHighlight(Highlight);
Did you find this page helpful?
React InstantSearch v6