API Reference / React InstantSearch Widgets / ToggleRefinement
Apr. 11, 2019

ToggleRefinement

Widget signature
<ToggleRefinement
  attribute={string}
  label={string}
  value={string|number|boolean}
  // Optional parameters
  defaultRefinement={boolean}
/>

About this widget

The ToggleRefinement widget provides an on/off filtering feature based on an attribute value.

Examples

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.

1
2
3
4
<ToggleRefinement
  // ...
  attribute="free_shipping"
/>
label
type: string
Required

The label to display for the checkbox.

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.

1
2
3
4
<ToggleRefinement
  // ...
  value={true}
/>
defaultRefinement
type: boolean
Optional

Whether the widget should be checked by default.

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

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

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.

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.

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

Toggles the refinement.

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.

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.

1
2
3
4
<CustomToggleRefinement
  // ...
  attribute="free_shipping"
/>
label
type: string
Required

The label to display for the refinement.

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.

1
2
3
4
<CustomToggleRefinement
  // ...
  value={true}
/>
defaultRefinement
type: boolean
Optional

Whether the widget should be checked by default.

1
2
3
4
<CustomToggleRefinement
  // ...
  defaultRefinement={true}
/>

Full example

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

HTML output

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>

Did you find this page helpful?