React-instantsearch: 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>