react-values
A set of tiny, composable React components for handling state with render props.
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, all based on JavaScripts native value types...
Any
values provide simple transforms likeset
andclear
.Array
values provide native methods likepush
,pop
,filter
, etc.Boolean
values providetoggle
, which we've all re-implemented 100 times.Date
values provide really helpful transforms likesetHours
andincrementMonth
.Map
values provide native methods likeset
,delete
andclear
.Number
values provideincrement
anddecrement
, which have also been re-written in every codebase ever.Object
values provide helpful transforms likeset
,unset
andassign
.Set
values provide native methods likeadd
,delete
andclear
.String
values provide native methods likeconcat
,repeat
,trim
, etc.
This saves you from constantly re-writing the same state management logic, so you can keep your components focused on behavior and presentation.
For example, here's a <Toggle>
implemented in just a few lines of code using a <BooleanValue>
:
import { BooleanValue } from 'react-values'
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>
)
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;
`
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—whether with this.setState
or by building the same action creators over and over. And for your components to be nicely reusable across your application you augment 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
-
Leverage render props. It uses a render-prop-based API, exposing its state and a handful of convenient transform functions to you with the flexible function-as-children pattern.
-
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. -
Follow JavaScript's conventions. It exposes JavaScript's familiar, built-in methods like
setDate/setHours
,push/pop
,filter
,concat
, etc. to avoid reinventing the wheel and forcing you to constantly read documentation. -
Be extremely lightweight. It's extremely lightweight (and tree-shakeable), with most components weighing just a few hundred bytes, so you can even import it from public-facing component libraries.
-
Prioritize convenience. It's designed to provide convenient functions like
increment
,toggle
, and smarter ones likeincrementDate
,decrementMonth
, so you can build complex interactions in just a few lines of code.
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.
- Counter — a simple counter using a
Number
and its convenience transforms. - Time Picker — a more complex time picker component, using
Date
and its convenience transforms. - Filtering — a basic
String
value used for filtering a list. - Checkbox Set — using a
Set
to keep track of a checkbox group. - Simple Tooltip — a simplistic tooltip implemented as a
Boolean
. - Simple Modal — a simplistic modal implemented as a
Boolean
.
If you have an idea for an example that shows a common use case, pull request it!