Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/matthewwithanm/react-controllables

Easily create controllable components
https://github.com/matthewwithanm/react-controllables

Last synced: about 1 month ago
JSON representation

Easily create controllable components

Awesome Lists containing this project

README 

        
react-controllables

===================



Easily create controllable components



If you've worked with forms in ReactJS, you're probably familiar with the idea

of [controlled and uncontrolled components][1]. Put simply, controlled

components have their state controlled by another component whereas uncontrolled

components manage their own state. It turns out that this idea can be really

useful for custom components too.



Use Case

--------



Imagine you've designed a TabBar component. When you click on a tab, it becomes

selected and the other tabs in the bar become deselected. The selected tab is

stored as state in the component. (As a pleasant side-effect, this makes it nice

and easy to demo in isolation.)



Everything is fine until one day when the designer of your site decides to add

another component to the page that also changes the selected tab. Now you've got

a problem: you need to hoist the state to a higher level so it can be shared

between the two components.



Instead of ripping out the state management from your TabBar component (which

would make it impossible to play with the component on a page by itself), make

it *controllable*.



How

---



1. Write a "dumb" component that doesn't manage its state at all but accepts one

   or more props and corresponding `onPROPNAMEChange` callbacks.

2. Use `controllable` to create a higher-order component from the dumb one.





  Note: There's one exception to the `onPROPNAMEChange` convention: if the prop

  name is "value," the callback will be simply "onChange". This is done to match

  the conventions in React itself.






  Note: react-controllables used to be implemented with a mixin and have a

  different (more complicated!) usage. The mixin is still included at

  react-controllables/mixin (or Controllables.Mixin in

  the standalone build) but deprecated. Switch!




Example

-------



We'll use our TabBar example and represent the selection as an integer using the

selectedTabIndex prop.



```jsx

class TabBar extends React.Component {



  render() {

    var selectedTabIndex = this.props.selectedTabIndex;

    return (

      
    

            
  • Tab Zero!
    • 

            
  • Tab One!
    • 

            
  • Tab Two!
    • 

          


    );

  }



  handleClick(event) {

    // Call the `onSelectedTabIndexChange` callback with the new value.

    if (!this.props.onSelectedTabIndexChange) return;

    var el = event.target;

    var index = Array.prototype.indexOf.call(el.parentNode.children, el);

    this.props.onSelectedTabIndexChange(index);

  }



}



TabBar.defaultProps = {selectedTabIndex: 0};



TabBar.propTypes = {

  selectedTabIndex: PropTypes.number.isRequired,

  onSelectedTabIndexChange: PropTypes.func,

};

```



Next, use the controllable util to create a higher-order component, telling it

which props you want to be managed.



```jsx

import controllable from 'react-controllables';

TabBar = controllable(TabBar, ['selectedTabIndex']);

```



We now have a TabBar component that can store its own state OR be controlled!

Just use it like normal:



```jsx



```



We can specify a value for it to start with using `defaultPROPNAME`:



```jsx



```



Or we can make it a *controlled* component and manage the state at a higher

level:



```jsx



```



Unlike React inputs, components built with react-controllables can't really be

said to be either "controlled" or "uncontrolled" generally. That's because a

single component can have both controlled and uncontrolled values. For example,

consider this variation of our TabBar:



```jsx

TabBar = controllable(TabBar, ['selectedTabIndex', 'color']);

```



We could have both "selectedTabIndex" and "color" be controlled:



```jsx



```



Or neither:



```jsx



```



(Remember, default values don't make a component controlled, they just set the

initial internal state.)



Or only one!



```jsx



```



Decorator Support

-----------------



The react-controllables API is also designed to work with [JavaScript decorator

proposal]. Decorators provide a very elegant way to use react-controllables (and

higher-order components in general) if you're using a transpiler that supports

them, like [Babel 5.0 or greater][2]:



```jsx

@controllable(['selectedTabIndex', 'color'])

class TabBar extends React.Component {



  // [SNIP] Body same as above.



}

```



[1]: http://facebook.github.io/react/docs/forms.html#controlled-components

[JavaScript decorator proposal]: https://github.com/wycats/javascript-decorators

[2]: http://babeljs.io/blog/2015/03/31/5.0.0/#stage-1:-decorators