A set of tiny, composable React components
for handling state with render props.

Why? · Principles · Examples · Documentation

react-values gives you a set of simple, composable helpers that let you build more complex, stateful UI components like toggles, dropdowns, lists, checkbox groups, popovers, tooltips, you name it!

It does this using a small render-prop-based API that exposes helpful transforms like toggle, increment, filter, etc. depending on the type of value, so that you don't have to re-write state management logic and can instead keep your components focused on behavior and presentation.

import { BooleanValue } from 'react-values'

const Track = styled.div`
  position: relative;
  height: 25px;
  width: 50px;
  background-color: ${props => (props.on ? 'lightgreen' : 'lightgray')};
  border-radius: 50px;
`

const Thumb = styled.div`
  position: absolute;
  left: ${props => (props.on ? '25px' : '0')};
  height: 25px;
  width: 25px;
  background-color: white;
  border-radius: 50px;
`

const Toggle = ({ value, defaultValue, onChange }) => (
  <BooleanValue value={value} defaultValue={defaultValue} onChange={onChange}>
    {({ value: on, toggle }) => (
      <Track on={on} onClick={toggle}>
        <Thumb on={on} />
      </Track>
    )}
  </BooleanValue>
)

Why?

While building an app with React, you end up building a lot of stateful components in the process. Whether at the UI kit level for things like toggles, tooltips, checkbox groups, dropdown, etc. Or at the app level for modals, popovers, sorting, filtering, etc.

In the process, you end up re-implementing run of the mill state handling logic all over the place, using this.setState and this.state. And for your components to be nicely reusable across your application you end up writing them to handle both "controlled" and "uncontrolled" use cases using value or defaultValue. And to make things a bit more manageable, you re-invent common transforms like open, close, toggle, increment, decrement, etc. in lots of different components. And if you're working with a team, you end up doing all of this in slightly different ways throughout your codebase.

In the end, you're now maintaing a lot more logic than necessary, duplicated in many different places in slightly different ways. All while your app's bundle size gets larger and larger.

react-values solves all of that with a few principles...

Principles

1. Leverage render props. It uses a render-prop-based API with children functions to expose its state, and to provide powerful transform functions that do the state management for you.

2. Follow React's conventions. Its components follow React's own naming conventions, using familiar concepts like value/defaultValue. This makes it extremely easy to slot into existing codebases or frameworks.

3. Follow JavaScript's conventions. It also leverages JavaScript's familiar, built-in methods like push/pop, filter, etc. so that it's not reinventing the wheel and forcing you to constantly re-read documentation.

4. Be extremely lightweight. It's extremely lightweight (and tree-shakeable), with most components weighing just a few hundred bytes, so you can even use it in public-facing components.

Examples

To get a sense for how you might use react-values, check out a few of the examples:

• Basic Toggle — using a Boolean to create a simple toggle component.
• Reusable Toggle — showing how you might turn that toggle into a controlled component in your own UI kit.

If you have an idea for an example that shows a common use case, pull request it!

Documentation

If you're using react-values for the first time, check out the Getting Started guide to familiarize yourself with how it works. Once you've done that, you'll probably want to check out the full API Reference.

• Getting Started
• Reference

If even that's not enough, you can always read the source itself, which is very simple!