diff --git a/docs/api/hooks.md b/docs/api/hooks.md index 1bcd43d0f..82ba8f6ec 100644 --- a/docs/api/hooks.md +++ b/docs/api/hooks.md @@ -11,6 +11,14 @@ React's new ["hooks" APIs](https://reactjs.org/docs/hooks-intro.html) give funct React Redux now offers a set of hook APIs as an alternative to the existing `connect()` Higher Order Component. These APIs allow you to subscribe to the Redux store and dispatch actions, without having to wrap your components in `connect()`. +:::tip + +**We recommend using the React-Redux hooks API as the default approach in your React components.** + +The existing `connect` API still works and will continue to be supported, but the hooks API is simpler and works better with TypeScript. + +::: + These hooks were first added in v7.1.0. ## Using Hooks in a React Redux App @@ -38,7 +46,11 @@ const result: any = useSelector(selector: Function, equalityFn?: Function) Allows you to extract data from the Redux store state, using a selector function. -> **Note**: The selector function should be [pure](https://en.wikipedia.org/wiki/Pure_function) since it is potentially executed multiple times and at arbitrary points in time. +:::info + +The selector function should be [pure](https://en.wikipedia.org/wiki/Pure_function) since it is potentially executed multiple times and at arbitrary points in time. + +::: The selector is approximately equivalent to the [`mapStateToProps` argument to `connect`](../using-react-redux/connect-mapstate) conceptually. The selector will be called with the entire Redux store state as its only argument. The selector will be run whenever the function component renders (unless its reference hasn't changed since a previous render of the component so that a cached result can be returned by the hook without re-running the selector). `useSelector()` will also subscribe to the Redux store, and run your selector whenever an action is dispatched. @@ -50,7 +62,11 @@ However, there are some differences between the selectors passed to `useSelector - Extra care must be taken when using memoizing selectors (see examples below for more details). - `useSelector()` uses strict `===` reference equality checks by default, not shallow equality (see the following section for more details). -> **Note**: There are potential edge cases with using props in selectors that may cause errors. See the [Usage Warnings](#usage-warnings) section of this page for further details. +:::info + +There are potential edge cases with using props in selectors that may cause issues. See the [Usage Warnings](#usage-warnings) section of this page for further details. + +::: You may call `useSelector()` multiple times within a single function component. Each call to `useSelector()` creates an individual subscription to the Redux store. Because of the React update batching behavior used in React Redux v7, a dispatched action that causes multiple `useSelector()`s in the same component to return new values _should_ only result in a single re-render. @@ -91,7 +107,7 @@ import React from 'react' import { useSelector } from 'react-redux' export const CounterComponent = () => { - const counter = useSelector((state) => state.counter) + const counter = useSelector(state => state.counter) return
- React Redux is maintained by the Redux team, and kept up-to-date with the latest APIs from Redux and React. + React Redux is maintained by the Redux team, and{' '} + + kept up-to-date with the latest APIs from Redux and React + + .
), image: , @@ -21,8 +25,9 @@ const features = [ { content: (- Designed to work with React's component model. - {' '} You define how to extract the values your component needs from Redux, and your component receives them as props. + Designed to work with React's component model. You + define how to extract the values your component needs from Redux, and + your component receives them as props.
), image: , @@ -32,7 +37,9 @@ const features = [ { content: (- Creates wrapper components that manage the store interaction logic for you, so you don't have to write it yourself. + Creates wrapper components that{' '} + manage the store interaction logic for you, so you + don't have to write it yourself.
), image: , @@ -42,13 +49,15 @@ const features = [ { content: (- Automatically implements complex performance optimizations, so that your own component only re-renders when the data it needs has actually changed. + Automatically implements{' '} + complex performance optimizations, so that your own + component only re-renders when the data it needs has actually changed.
), image: , imageAlign: 'top', title: 'Optimized' - }, + } ] const otherLibraries = [ @@ -66,10 +75,11 @@ const otherLibraries = [ >