<ToggleRefinement>

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

<ToggleRefinement
  attribute={string}
  // Optional parameters
  label={string}
  on={boolean | number | string}
  off={boolean | number | string}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>

1
import { ToggleRefinement } from 'react-instantsearch';

1
2
3
4
5
6
7
8
9
10
11
12
13
import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, ToggleRefinement } from 'react-instantsearch';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <ToggleRefinement attribute="free_shipping" />
    </InstantSearch>
  );
}

1
<ToggleRefinement attribute="free_shipping" />

1
2
3
4
<ToggleRefinement
  // ...
  label="Free shipping"
/>

1
2
3
4
<ToggleRefinement
  // ...
  on={true}
/>

1
2
3
4
<ToggleRefinement
  // ...
  on={1}
/>

1
2
3
4
<ToggleRefinement
  // ...
  on="yes"
/>

1
2
3
4
<ToggleRefinement
  // ...
  off={false}
/>

1
2
3
4
<ToggleRefinement
  // ...
  off={0}
/>

1
2
3
4
<ToggleRefinement
  // ...
  off="no"
/>

1
2
3
4
5
6
7
<ToggleRefinement
  // ...
  classNames={{
    root: 'MyCustomToggleRefinement',
    checkbox: 'MyCustomToggleRefinementCheckbox MyCustomToggleRefinementCheckbox--subclass',
  }}
/>

1
2
3
4
5
<ToggleRefinement
  // ...
  className="MyCustomToggleRefinement"
  title="My custom title"
/>

Hook

React InstantSearch let you create your own UI for the <ToggleRefinement> widget with useToggleRefinement(). Hooks provide APIs to access the widget state and interact with InstantSearch.

The useToggleRefinement() Hook accepts parameters and returns APIs.

Usage

First, create your React component:

import { useToggleRefinement } from 'react-instantsearch';

function CustomToggleRefinement(props) {
  const {
    value,
    canRefine,
    refine,
    sendEvent,
    createURL,
  } = useToggleRefinement(props);

  return <>{/* Your JSX */}</>;
}

Then, render the widget:

<CustomToggleRefinement {...props} />

Parameters

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

1
2
3
const toggleRefinementApi = useToggleRefinement({
  attribute: 'free_shipping',
});

1
2
3
4
const toggleRefinementApi = useToggleRefinement({
  // ...
  on: true,
});

1
2
3
4
const toggleRefinementApi = useToggleRefinement({
  // ...
  on: 1,
});

1
2
3
4
const toggleRefinementApi = useToggleRefinement({
  // ...
  on: 'yes',
});

1
2
3
4
const toggleRefinementApi = useToggleRefinement({
  // ...
  off: false,
});

1
2
3
4
const toggleRefinementApi = useToggleRefinement({
  // ...
  off: 0,
});

1
2
3
4
const toggleRefinementApi = useToggleRefinement({
  // ...
  off: 'no',
});

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

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
28
29
30
31
32
33
type ToggleRefinementValue = {
  /**
  * The attribute name of this toggle.
  */
  name: string;
  /**
  * Whether the current option is "on" (true) or "off" (false)
  */
  isRefined: boolean;
  /**
  * Number of results if this option is toggled.
  */
  count: number | null;
  /**
  * Information about the "on" toggle.
  */
  onFacetValue: ToggleRefinementDetails;
  /**
  * Information about the "off" toggle.
  */
  offFacetValue: ToggleRefinementDetails;
};

type ToggleRefinementDetails = {
  /**
  * whether this option is enabled.
  */
  isRefined: boolean;
  /**
  * Number of result if this option is toggled.
  */
  count: number | null;
};

1
2
3
const { canRefine } = useToggleRefinement({ attribute: 'free_shipping' });

return <input disabled={!canRefine} type="checkbox" />;

1
2
3
4
5
6
7
8
const { refine } = useToggleRefinement({ attribute: 'free_shipping' });

return (
  <input
    onChange={event => refine({ isRefined: !event.target.checked })}
    type="checkbox"
  />
);

1
2
3
4
5
6
7
8
9
10
11
12
13
sendEvent('click', true);

// This sends a similar payload to the `insights` middleware.
// {
//   eventType: 'click',
//   insightsMethod: 'clickedFilters',
//   payload: {
//     eventName: 'Filter Applied',
//     filters: ['free_shipping:true'],
//     index: '',
//   },
//   widgetType: 'ais.toggleRefinement',
// }

1
2
3
4
5
6
7
8
9
10
const { createURL, value, refine } = useToggleRefinement({ attribute: 'free_shipping' });

return (
  <a
    href={createURL()}
    onClick={event => refine({ isRefined: !value.isRefined })}
  >
    Link to the next state
  </a>
);

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import React from 'react';
import { useToggleRefinement } from 'react-instantsearch';

function CustomToggleRefinement(props) {
  const { value, refine } = useToggleRefinement(props);

  return (
    <label>
      <input
        type="checkbox"
        checked={value.isRefined}
        onChange={(event) => {
          refine({ isRefined: !event.target.checked });
        }}
      />

      <span>{props.attribute}</span>
    </label>
  );
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import React from 'react';
import {
  useToggleRefinement,
  UseToggleRefinementProps,
} from 'react-instantsearch';

function CustomToggleRefinement(props: UseToggleRefinementProps) {
  const { value, refine } = useToggleRefinement(props);

  return (
    <label>
      <input
        type="checkbox"
        checked={value.isRefined}
        onChange={(event) => {
          refine({ isRefined: !event.target.checked });
        }}
      />

      <span>{props.attribute}</span>
    </label>
  );
}