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:
- The way it works
- 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 stateChangeTypes
so 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! 👍