This post is here for historical reasons. Please read an updated version of this blog post with React Hooks! You may also be interested in the more general concept of "Inversion of Control".

This last week, @notruth (new code contributor to the downshift project), filed an issue: "closeOnSelection" property (Multiple selection out of box). All you really need to know about that issue is that the decisions made about how downshift updates its state based on user interaction in certain scenarios didn't agree with what @notruth wants for their implementation. 😖

Why do we use UI libraries?

With UI libraries like downshift, you can offer two things:

1. The way it works
2. The way it looks

UI libraries have to make decisions about these things to be useful at all. But the fewer decisions you make, the more generically useful and flexible (lego-block-like) your library can be. However, it's a delicate balance. The more decisions you make, the more useful you can be for some use cases, but you run the risk of becoming too opinionated and totally unusable for other use cases. If you make no decisions at all, then ummm... why am I installing your library? 🤔

For downshift, I decided to not make any decisions about the way it looks by using a render prop. I did this because with "enhanced input components" (like autocomplete), the part we're trying to abstract away is the way it works, and the part we want to grant the most flexibility is the way it looks. In addition, with a render prop, it's trivial for other people to build another component on top of downshift to provide a good default for the way it looks and publish that (I'm still sorta surprised nobody's done that yet). 🤨

Imperfect assumptions

That said, sometimes, the decisions I made about the way downshift works don't quite satisfy all the use cases people are looking to use downshift for. For example, downshift will set the isOpen state of the menu to false when the user selects an item and in the issue @notruth posted, they are saying that decision doesn't fit their use case. 🤷‍♂️

This is one reason why downshift supports control props. It allows you to have complete control over the internal state of downshift. In this case, @notruth could have controlled the isOpen state and use the onStateChange to know when to update their version of that state. However, that's a fair amount of work, so it's understandable why @notruth would prefer an easier method. But the suggestion of adding a new prop for that didn't seem to provide the benefit to offset the cost of increasing the API surface area of downshift. So giving it a little more thought gave me an idea of how we could simplify this and reduce boilerplate further. 😈

A simpler API

That's when I came up with a new prop I initially called modifyStateChange. Because downshift already supports control props, it isolates state changes to an internal method called internalSetState. It's a surprisingly long method (mostly because it's highly commented). This isolation made the implementation of this new feature trivial. Any time we make state changes, we first call a method to see if the user of downshift is interested in making any changes to the state change that's about to take place. 🤓

An important element to this as well is the ability for the user to determine what kind of state change is taking place. In the case of @notruth, they only want to prevent isOpen from changing to false if the user selects (keydown/click) on an item. So they need to know what type of change is about to happen. Luckily, we needed this distinction for onStateChange as well and already had this mechanism in place! It's called stateChangeTypes (here's the current list). 🤖

So, @notruth opened the pull request to add the modifyStateChange. After considering it a little further, I decided that this could be generalized into a pattern that could be really useful for other libraries. Patterns are much easier to evangelize when they have a name, so I looked for one. 🕵️

Introducing the state reducer pattern

I eventually settled on the name "state reducer" and changed the API slightly to resemble a reducer function. Your function gets two arguments: 1) the current state of downshift, 2) the upcoming changes. Your job is to "reduce" that to the changes you want to take place. Also, the upcoming changes have a type that correspond to the stateChangeTypesso you know whether you want your logic to apply. You might think of the changes as an "action" in redux (it has a type), but what you return isn't the whole state (like you would in redux), just the changes you want made to the state. 🔁

A few people have since let me know that reason-react has something similar to this called simply "reducer" which is validating because I think Reason is pretty neat. 💡

So, without further ado, here is a very simple "state reducer" implementation with downshift that prevents the menu from closing after the user selects an item. Here's the stateReducer prop:

import Downshift from 'downshift'

function stateReducer(state, changes) {
	switch (changes.type) {
		case Downshift.stateChangeTypes.keyDownEnter:
		case Downshift.stateChangeTypes.clickItem:
			return {
				...changes,
				isOpen: state.isOpen,
				highlightedIndex: state.highlightedIndex,
			}
		default:
			return changes
	}
}

This is a fairly loose API, but because all the state in downshift is controllable anyway (via control props) this doesn't actually allow you to do anything you weren't already able to accomplish yourself, it just reduces (no pun intended 😆) the boilerplate and wiring that are necessary to tweak "the way it works" with regard to downshift and its state. 👌

The implementation in downshift is probably not altogether straightforward I'm afraid (downshift is not a simple component). Which is why I've created this simplified example implementation for a toggle component: https://codesandbox.io/s/4qo58nvl3x. Note that it's a little bit overkill for a toggle component, but hopefully it gets the point across of one way you could implement this pattern. 🤝

Conclusion

I'm really excited by this new pattern that I see sits in the sweet spot between an uncontrolled and an controlled component. I think it'll do a better job allowing our libraries to satisfy more use cases for "the way it works" without all the boilerplate and wiring up required by users of the Control Props pattern. (And yes, I'll eventually be updating my egghead.io course to include a lesson on the reducer pattern). Good luck! 👍