This site runs best with JavaScript enabled.

The State Reducer Pattern with React Hooks


A pattern for you to use in custom hooks to enhance the power and flexibility of your hooks.

Some History

About a year ago, I developed a new pattern for enhancing your React components called the state reducer pattern. I used it in downshift to enable an awesome API for people who wanted to make changes to how downshift updates state internally.

If you're unfamiliar with downshift, just know that it's an "enhanced input" component that allows you to build things like accessible autocomplete/typeahead/dropdown components. It's important to know that it manages the following items of state: isOpen, selectedItem, highlightedIndex, and inputValue.

Downshift is currently implemented as a render prop component, because at the time, render props was the best way to make a "Headless UI Component" (typically implemented via a "render prop" API) which made it possible for you to share logic without being opinionated about the UI. This is the major reason that downshift is so successful.

Today however, we have React Hooks and hooks are way better at doing this than render props. So I thought I'd give you all an update of how this pattern transfers over to this new API the React team has given us. (Note: Downshift has plans to implement a hook)

As a reminder, the benefit of the state reducer pattern is in the fact that it allows "inversion of control" which is basically a mechanism for the author of the API to allow the user of the API to control how things work internally. For an example-based talk about this, I strongly recommend you give my React Rally 2018 talk a watch:

So in the downshift example, I had made the decision that when an end user selects an item, the isOpen should be set to false (and the menu should be closed). Someone was building a multi-select with downshift and wanted to keep the menu open after the user selects an item in the menu (so they can continue to select more).

By inverting control of state updates with the state reducer pattern, I was able to enable their use case as well as any other use case people could possibly want when they want to change how downshift operates internally. Inversion of control is an enabling computer science principle and the state reducer pattern is an awesome implementation of that idea that translates even better to hooks than it did to regular components.

Using a State Reducer with Hooks

Ok, so the concept goes like this:

  1. End user does an action
  2. Dev calls dispatch
  3. Hook determines the necessary changes
  4. Hook calls dev's code for further changes 👈 this is the inversion of control part
  5. Hook makes the state changes

WARNING: Contrived example ahead: To keep things simple, I'm going to use a simple useToggle hook and component as a starting point. It'll feel contrived, but I don't want you to get distracted by a complicated example as I teach you how to use this pattern with hooks. Just know that this pattern works best when it's applied to complex hooks and components (like downshift).

1function useToggle() {
2 const [on, setOnState] = React.useState(false)
3
4 const toggle = () => setOnState(o => !o)
5 const setOn = () => setOnState(true)
6 const setOff = () => setOnState(false)
7
8 return {on, toggle, setOn, setOff}
9}
10
11function Toggle() {
12 const {on, toggle, setOn, setOff} = useToggle()
13
14 return (
15 <div>
16 <button onClick={setOff}>Switch Off</button>
17 <button onClick={setOn}>Switch On</button>
18 <Switch on={on} onClick={toggle} />
19 </div>
20 )
21}
22
23function App() {
24 return <Toggle />
25}
26
27ReactDOM.render(<App />, document.getElementById('root'))

Now, let's say we wanted to adjust the <Toggle /> component so the user couldn't click the <Switch /> more than 4 times in a row unless they click a "Reset" button:

1function Toggle() {
2 const [clicksSinceReset, setClicksSinceReset] = React.useState(0)
3 const tooManyClicks = clicksSinceReset >= 4
4
5 const {on, toggle, setOn, setOff} = useToggle()
6
7 function handleClick() {
8 toggle()
9 setClicksSinceReset(count => count + 1)
10 }
11
12 return (
13 <div>
14 <button onClick={setOff}>Switch Off</button>
15 <button onClick={setOn}>Switch On</button>
16 <Switch on={on} onClick={handleClick} />
17 {tooManyClicks ? (
18 <button onClick={() => setClicksSinceReset(0)}>Reset</button>
19 ) : null}
20 </div>
21 )
22}

Cool, so an easy solution to this problem would be to add an if statement in the handleClick function and not call toggle if tooManyClicks is true, but let's keep going for the purposes of this example.

How could we change the useToggle hook, to invert control in this situation? Let's think about the API first, then the implementation second. As a user, it'd be cool if I could hook into every state update before it actually happens and modify it, like so:

1function Toggle() {
2 const [clicksSinceReset, setClicksSinceReset] = React.useState(0)
3 const tooManyClicks = clicksSinceReset >= 4
4
5 const {on, toggle, setOn, setOff} = useToggle({
6 modifyStateChange(currentState, changes) {
7 if (tooManyClicks) {
8 // other changes are fine, but on needs to be unchanged
9 return {...changes, on: currentState.on}
10 } else {
11 // the changes are fine
12 return changes
13 }
14 },
15 })
16
17 function handleClick() {
18 toggle()
19 setClicksSinceReset(count => count + 1)
20 }
21
22 return (
23 <div>
24 <button onClick={setOff}>Switch Off</button>
25 <button onClick={setOn}>Switch On</button>
26 <Switch on={on} onClick={handleClick} />
27 {tooManyClicks ? (
28 <button onClick={() => setClicksSinceReset(0)}>Reset</button>
29 ) : null}
30 </div>
31 )
32}

So that's great, except it prevents changes from happening when people click the "Switch Off" or "Switch On" buttons, and we only want to prevent the <Switch /> from toggling the state.

Hmmm... What if we change modifyStateChange to be called reducer and it accepts an action as the second argument? Then the action could have a type that determines what type of change is happening, and the changes could just be a property on that object. We'll just say that the type for clicking the switch is TOGGLE.

1function Toggle() {
2 const [clicksSinceReset, setClicksSinceReset] = React.useState(0)
3 const tooManyClicks = clicksSinceReset >= 4
4
5 const {on, toggle, setOn, setOff} = useToggle({
6 reducer(currentState, action) {
7 if (tooManyClicks && action.type === 'TOGGLE') {
8 // other changes are fine, but on needs to be unchanged
9 return {...action.changes, on: currentState.on}
10 } else {
11 // the changes are fine
12 return action.changes
13 }
14 },
15 })
16
17 function handleClick() {
18 toggle()
19 setClicksSinceReset(count => count + 1)
20 }
21
22 return (
23 <div>
24 <button onClick={setOff}>Switch Off</button>
25 <button onClick={setOn}>Switch On</button>
26 <Switch on={on} onClick={handleClick} />
27 {tooManyClicks ? (
28 <button onClick={() => setClicksSinceReset(0)}>Reset</button>
29 ) : null}
30 </div>
31 )
32}

Nice! This gives us all kinds of control. One last thing, let's not bother with the string 'TOGGLE' for the type. Instead we'll have an object of all the change types that people can reference instead. This'll help avoid typos and improve editor autocompletion:

1function Toggle() {
2 const [clicksSinceReset, setClicksSinceReset] = React.useState(0)
3 const tooManyClicks = clicksSinceReset >= 4
4
5 const {on, toggle, setOn, setOff} = useToggle({
6 reducer(currentState, action) {
7 if (tooManyClicks && action.type === useToggle.types.toggle) {
8 // other changes are fine, but on needs to be unchanged
9 return {...action.changes, on: currentState.on}
10 } else {
11 // the changes are fine
12 return action.changes
13 }
14 },
15 })
16
17 function handleClick() {
18 toggle()
19 setClicksSinceReset(count => count + 1)
20 }
21
22 return (
23 <div>
24 <button onClick={setOff}>Switch Off</button>
25 <button onClick={setOn}>Switch On</button>
26 <Switch on={on} onClick={handleClick} />
27 {tooManyClicks ? (
28 <button onClick={() => setClicksSinceReset(0)}>Reset</button>
29 ) : null}
30 </div>
31 )
32}

Implementing a State Reducer with Hooks

Alright, I'm happy with the API we're exposing here. Let's take a look at how we could implement this with our useToggle hook. In case you forgot, here's the code for that:

1function useToggle() {
2 const [on, setOnState] = React.useState(false)
3
4 const toggle = () => setOnState(o => !o)
5 const setOn = () => setOnState(true)
6 const setOff = () => setOnState(false)
7
8 return {on, toggle, setOn, setOff}
9}

We could add logic to every one of these helper functions, but I'm just going to skip ahead and tell you that this would be really annoying, even in this simple hook. Instead, we're going to rewrite this from useState to useReducer and that'll make our implementation a LOT easier:

1function toggleReducer(state, action) {
2 switch (action.type) {
3 case 'TOGGLE': {
4 return {on: !state.on}
5 }
6 case 'ON': {
7 return {on: true}
8 }
9 case 'OFF': {
10 return {on: false}
11 }
12 default: {
13 throw new Error(`Unhandled type: ${action.type}`)
14 }
15 }
16}
17
18function useToggle() {
19 const [{on}, dispatch] = React.useReducer(toggleReducer, {on: false})
20
21 const toggle = () => dispatch({type: 'TOGGLE'})
22 const setOn = () => dispatch({type: 'ON'})
23 const setOff = () => dispatch({type: 'OFF'})
24
25 return {on, toggle, setOn, setOff}
26}

Ok, cool. Really quick, let's add that types property to our useToggle to avoid the strings thing:

1function toggleReducer(state, action) {
2 switch (action.type) {
3 case useToggle.types.toggle: {
4 return {on: !state.on}
5 }
6 case useToggle.types.on: {
7 return {on: true}
8 }
9 case useToggle.types.off: {
10 return {on: false}
11 }
12 default: {
13 throw new Error(`Unhandled type: ${action.type}`)
14 }
15 }
16}
17
18function useToggle() {
19 const [{on}, dispatch] = React.useReducer(toggleReducer, {on: false})
20
21 const toggle = () => dispatch({type: useToggle.types.toggle})
22 const setOn = () => dispatch({type: useToggle.types.on})
23 const setOff = () => dispatch({type: useToggle.types.off})
24
25 return {on, toggle, setOn, setOff}
26}
27
28useToggle.types = {
29 toggle: 'TOGGLE',
30 on: 'ON',
31 off: 'OFF',
32}

Cool, so now, users are going to pass reducer as a configuration object to our useToggle function, so let's accept that:

1function useToggle({reducer}) {
2 const [{on}, dispatch] = React.useReducer(toggleReducer, {on: false})
3
4 const toggle = () => dispatch({type: useToggle.types.toggle})
5 const setOn = () => dispatch({type: useToggle.types.on})
6 const setOff = () => dispatch({type: useToggle.types.off})
7
8 return {on, toggle, setOn, setOff}
9}

Great, so now that we have the developer's reducer, how do we combine that with our reducer? Well remember that the developer needs to know what our changes will be, so we'll definitely need to determine those changes first. Let's make an inline reducer:

1function useToggle({reducer}) {
2 const [{on}, dispatch] = React.useReducer(
3 (state, action) => {
4 const changes = toggleReducer(state, action)
5 return changes
6 },
7 {on: false},
8 )
9
10 const toggle = () => dispatch({type: useToggle.types.toggle})
11 const setOn = () => dispatch({type: useToggle.types.on})
12 const setOff = () => dispatch({type: useToggle.types.off})
13
14 return {on, toggle, setOn, setOff}
15}

That was a straight-up refactor. In fact, no functionality has changed for our toggle hook (which is actually kinda neat if you think of it. The magic of black boxes and implementation details ✨).

Awesome, so now we have all the info we need to pass along to the reducer they've given to us:

1function useToggle({reducer}) {
2 const [{on}, dispatch] = React.useReducer(
3 (state, action) => {
4 const changes = toggleReducer(state, action)
5 return reducer(state, {...action, changes})
6 },
7 {on: false},
8 )
9
10 const toggle = () => dispatch({type: useToggle.types.toggle})
11 const setOn = () => dispatch({type: useToggle.types.on})
12 const setOff = () => dispatch({type: useToggle.types.off})
13
14 return {on, toggle, setOn, setOff}
15}

Cool! So we just call the developer's reducer with the state and make a new action object that has all the properties of the original action plus the changes. Then we return whatever they return to us. And they have complete control over our state updates! That's pretty neat! And thanks to useReducer it's pretty simple too.

But not everyone's going to need this reducers feature, so let's default the configuration object to {} and we'll default the reducer property to a simple reducer that just always returns the changes:

1function useToggle({reducer = (s, a) => a.changes} = {}) {
2 const [{on}, dispatch] = React.useReducer(
3 (state, action) => {
4 const changes = toggleReducer(state, action)
5 return reducer(state, {...action, changes})
6 },
7 {on: false},
8 )
9
10 const toggle = () => dispatch({type: useToggle.types.toggle})
11 const setOn = () => dispatch({type: useToggle.types.on})
12 const setOff = () => dispatch({type: useToggle.types.off})
13
14 return {on, toggle, setOn, setOff}
15}

Conclusion

Here's the final version:

1import React from 'react'
2import ReactDOM from 'react-dom'
3import Switch from './switch'
4
5function toggleReducer(state, action) {
6 switch (action.type) {
7 case useToggle.types.toggle: {
8 return {on: !state.on}
9 }
10 case useToggle.types.on: {
11 return {on: true}
12 }
13 case useToggle.types.off: {
14 return {on: false}
15 }
16 default: {
17 throw new Error(`Unhandled type: ${action.type}`)
18 }
19 }
20}
21
22function useToggle({reducer = (s, a) => a.changes} = {}) {
23 const [{on}, dispatch] = React.useReducer(
24 (state, action) => {
25 const changes = toggleReducer(state, action)
26 return reducer(state, {...action, changes})
27 },
28 {on: false},
29 )
30
31 const toggle = () => dispatch({type: useToggle.types.toggle})
32 const setOn = () => dispatch({type: useToggle.types.on})
33 const setOff = () => dispatch({type: useToggle.types.off})
34
35 return {on, toggle, setOn, setOff}
36}
37useToggle.types = {
38 toggle: 'TOGGLE',
39 on: 'ON',
40 off: 'OFF',
41}
42
43function Toggle() {
44 const [clicksSinceReset, setClicksSinceReset] = React.useState(0)
45 const tooManyClicks = clicksSinceReset >= 4
46
47 const {on, toggle, setOn, setOff} = useToggle({
48 reducer(currentState, action) {
49 if (tooManyClicks && action.type === useToggle.types.toggle) {
50 // other changes are fine, but on needs to be unchanged
51 return {...action.changes, on: currentState.on}
52 } else {
53 // the changes are fine
54 return action.changes
55 }
56 },
57 })
58
59 return (
60 <div>
61 <button onClick={setOff}>Switch Off</button>
62 <button onClick={setOn}>Switch On</button>
63 <Switch
64 onClick={() => {
65 toggle()
66 setClicksSinceReset(count => count + 1)
67 }}
68 on={on}
69 />
70 {tooManyClicks ? (
71 <button onClick={() => setClicksSinceReset(0)}>Reset</button>
72 ) : null}
73 </div>
74 )
75}
76
77function App() {
78 return <Toggle />
79}
80
81ReactDOM.render(<App />, document.getElementById('root'))

And here it is running in a codesandbox:

Remember, what we've done here is enable users to hook into every state update of our reducer to make changes to it. This makes our hook WAY more flexible, but it also means that the way we update state is now part of the API and if we make changes to how that happens, then it could be a breaking change for users. It's totally worth the trade-off for complex hooks/components, but it's just good to keep that in mind.

I hope you find patterns like this useful. Thanks to useReducer, this pattern just kinda falls out (thank you React!). So give it a try on your codebase!

Good luck!

Discuss on TwitterEdit post on GitHub

Share article
loading relevant upcoming workshops...
Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.