API Reference / React InstantSearch Widgets / Highlight
Apr. 24, 2019

Highlight

Widget signature 
<Highlight
  attribute={string}
  hit={object}
  // Optional parameters
  tagName={string}
  nonHighlightedTagName={string}
  separator={React.Node}
/>
See code examples
See Live example

About this widget #

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.
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=" - "
/>

Customize the UI - 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#

Edit
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);

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>

Did you find this page helpful?

React InstantSearch v5