Guide: Be clearer about the default refinement behaviour and how refine is working

[mthuret]

See #61.

We should explain in our documentation that when clearing all refinements, default refinements are not removed.

In the same time it would be nice to check for every connector how their refine function works, to set or remove a refinement. It should be consistent, but today it's not (for instance: connectRange).

We should wrote a guide about those results.

[davidfurlong]

Thanks for moving the issue. I'd like to add that currently removing the refinement for connectRange using refine seems to be impossible once set - refine(null) and refine({min: null, max: null}) both don't work. It may even make more sense to provide another function in the props which removes a refinement, rather than overloading the refine function

Edit: it seems that one can remove the refinement from a connectRange by using refine.bind(null, item.value) from within CurrentRefinements.

[davidfurlong]

Are defaultRefinements cleared on a clearAll? My code seems to behave as such. So the suggestion of VirtualWidgets is kind of mute when their values are still cleared on a clearAll. https://community.algolia.com/react-instantsearch/guide/Virtual_widgets.html

Hiding default refinements 
In some situations not only you want default refinements but you also do not want the user to be able to unselect them.

[samouss]

Yes the defaultRefinement are clear when ClearAll is clicked.

As a workaround you can filter the items to clear with the transformItems prop. In the following example all the current refinement are removed, except the category of the VirtualMenu.

<InstantSearch
  appId="latency"
  apiKey="6be0576ff61c053d5f9a3225e2a90f76"
  indexName="bestbuy"
>
  <VirtualMenu 
    attributeName="category" 
    defaultRefinement="Dining" 
  />

  <RefinementList 
    attributeName="materials" 
    defaultRefinement={["Polyamide"]} 
  />

  <ClearAll
    transformItems={items => items.filter(item => item.attributeName !== "category")}
  />

  <Hits />
</InstantSearch>

[njbarrett]

@samouss thanks that's exactly what I was looking for. I think the documentation could be clearer on this.

[albertojacini]

As of v5.0 use 'attribute' instead of 'attributeName' to make it work:

<InstantSearch
  appId="latency"
  apiKey="6be0576ff61c053d5f9a3225e2a90f76"
  indexName="bestbuy"
>
  <VirtualMenu 
    attribute="category" 
    defaultRefinement="Dining" 
  />

  <RefinementList 
    attribute="materials" 
    defaultRefinement={["Polyamide"]} 
  />

  <ClearAll
    transformItems={items => items.filter(item => item.attribute !== "category")}
  />

  <Hits />
</InstantSearch>

[FabienMotte]

Hey!

We're doing a round of clean up before migrating this repository to the new InstantSearch monorepo. This issue seems not to have generated much activity lately and to be mostly solved by the shared code snippet, so we're going to close it.

Here's a sandbox using React InstantSearch Hooks: https://codesandbox.io/s/upbeat-forest-hpnq58?file=/src/App.tsx

To clear the active refinements, you can now use the <ClearRefinements> widget with React InstantSearch Hooks. You can also exclude attributes from the refinements to clear using the excludedAttributes prop.

Default refinements are now defined by passing an initialUiState prop on the <InstantSearch> component. As you can see on the sandbox, default refinements are cleared by the <ClearRefinements> widget (unless they are excluded).

We recommend anyone who is currently using React InstantSearch v6 to migrate to Hooks.