API Reference / React InstantSearch / Snippet

Snippet

Signature 
<Snippet
  attribute={string}
  hit={object}
  // Optional parameters
  tagName={string}
  nonHighlightedTagName={string}
  separator={React.Node}
/>
Import
Copy 
1

import { Snippet } from 'react-instantsearch-dom';
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 Snippet widget displays snippeted 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

{
  "_snippetResult": {
    "attributeName": {
      "value": "..."
    }
  }
}

The attribute must be set up in attributesToSnippet either inside the Algolia dashboard or at runtime:

Copy 
1

<Configure attributesToSnippet={['description']} />

Examples

Copy 
1
2
3
4
5

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

const Hit = ({ hit }) => <Snippet hit={hit} attribute="description" />;

<Hits hitComponent={Hit} />

Props

attribute
type: string
Required

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

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

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

<Snippet
  // ...
  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

<Snippet
  // ...
  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

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

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

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

HTML output

Copy 
1
2
3
4

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

Or with mark as the tagName:

Copy 
1
2
3
4

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

Customize the UI with connectHighlight

If you want to create your own UI of the Snippet 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: Highlight

It’s a 3-step process:

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

// 2. Connect the component using the connector
const CustomSnippet = connectHighlight(Snippet);

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

See code examples

Create a React component

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

Provided Props

highlight
type: function

A function to which you provide the property which contains the snippeting (always _snippetResult). It returns an array of objects, with an isHighlighted boolean property to say whether this part should be in the tag for snippeting 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 Snippet = ({ highlight, attribute, hit }) => {
  const parsedHit = highlight({
    highlightProperty: '_snippetResult',
    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 CustomSnippet = connectHighlight(Snippet);

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

Exposed Props

attribute
type: string
Required

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

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

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

<CustomSnippet
  // ...
  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 Snippet = ({ highlight, attribute, hit }) => {
  const parsedHit = highlight({
    highlightProperty: '_snippetResult',
    attribute,
    hit,
  });

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

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