API Reference / React InstantSearch / ToggleRefinement

ToggleRefinement

Signature 
<ToggleRefinement
  attribute={string}
  label={string}
  value={string|number|boolean}
  // Optional parameters
  defaultRefinement={boolean}
/>
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 ToggleRefinement widget provides an on/off filtering feature based on an attribute value.

Requirements

Ensure that the attribute provided is already declared as an attribute for faceting.

Examples

Copy 
1
2
3
4
5
6
7

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

<ToggleRefinement
  attribute="free_shipping"
  label="Free Shipping"
  value={true}
/>

Props

attribute
type: string
Required

The name of the attribute on which to apply the refinement.
Copy 
1
2
3
4

<ToggleRefinement
  // ...
  attribute="free_shipping"
/>
label
type: string
Required

The label to display for the checkbox.
Copy 
1
2
3
4

<ToggleRefinement
  // ...
  label="Free Shipping"
/>
value
type: string|number|boolean
Required

The value to apply on the attribute when the widget is checked.
Copy 
1
2
3
4

<ToggleRefinement
  // ...
  value={true}
/>
defaultRefinement
type: boolean
Optional

Whether the widget should be checked by default.
Copy 
1
2
3
4

<ToggleRefinement
  // ...
  defaultRefinement={true}
/>

HTML output

Copy 
1
2
3
4
5
6

<div class="ais-ToggleRefinement">
  <label class="ais-ToggleRefinement-label">
    <input class="ais-ToggleRefinement-checkbox" type="checkbox" />
    <span class="ais-ToggleRefinement-labelText">Free Shipping</span>
  </label>
</div>

Customize the UI with connectToggleRefinement

If you want to create your own UI of the ToggleRefinement 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.

It’s a 3-step process:

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

// 2. Connect the component using the connector
const CustomToggleRefinement = connectToggleRefinement(ToggleRefinement);

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

See code examples

Create a React component

const ToggleRefinement = ({
  boolean currentRefinement,
  object count,
  function refine,
  function createURL,
}) => {
  // return the DOM output
};

Provided Props

currentRefinement
type: boolean

The current state of the widget: true when the refinement is applied, false otherwise.
Copy 
1
2
3
4
5

const ToggleRefinement = ({ currentRefinement }) => (
  <p>
    The value of the Toggle is <code>{currentRefinement.toString()}</code>.
  </p>
);
count
type: object

Contains the count for the checked and the unchecked state. The count represents the number of results that matched after applying the refinement.
Copy 
1
2
3

const ToggleRefinement = ({ currentRefinement, count }) => (
  <p>{currentRefinement ? count.checked : count.unchecked} hits matched.</p>
);
refine
type: function

Toggles the refinement.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12

const ToggleRefinement = ({ currentRefinement, refine }) => (
  <a
    href="#"
    style={{ fontWeight: currentRefinement ? 'bold' : '' }}
    onClick={event => {
      event.preventDefault();
      refine(!currentRefinement);
    }}
  >
    Free Shipping
  </a>
);
createURL
type: function

Generates a URL for the corresponding search state.
Copy 
1
2
3

const ToggleRefinement = ({ currentRefinement, createURL }) => (
  <a href={createURL(!currentRefinement)}>Free Shipping</a>
);

Create and instantiate your connected widget

const CustomToggleRefinement = connectToggleRefinement(ToggleRefinement);

<CustomToggleRefinement
  attribute={string}
  label={string}
  value={string|number|boolean}
  // optional parameters
  defaultRefinement={boolean}
/>

Exposed Props

attribute
type: string
Required

The name of the attribute on which to apply the refinement.
Copy 
1
2
3
4

<CustomToggleRefinement
  // ...
  attribute="free_shipping"
/>
label
type: string
Required

The label to display for the refinement.
Copy 
1
2
3
4

<CustomToggleRefinement
  // ...
  label="Free Shipping"
/>
value
type: string|number|boolean
Required

The value of the refinement to apply on the attribute when checked.
Copy 
1
2
3
4

<CustomToggleRefinement
  // ...
  value={true}
/>
defaultRefinement
type: boolean
Optional

Whether the widget should be checked by default.
Copy 
1
2
3
4

<CustomToggleRefinement
  // ...
  defaultRefinement={true}
/>

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

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

const ToggleRefinement = ({
  currentRefinement,
  label,
  count,
  refine,
  createURL,
}) => (
  <a
    href={createURL(!currentRefinement)}
    style={{ fontWeight: currentRefinement ? 'bold' : '' }}
    onClick={event => {
      event.preventDefault();
      refine(!currentRefinement);
    }}
  >
    {label} ({currentRefinement ? count.checked : count.unchecked})
  </a>
);

const CustomToggleRefinement = connectToggleRefinement(ToggleRefinement);
Did you find this page helpful?
React InstantSearch v6