A React mixin that provides two-way data binding for components using ImmutableJS data structures as properties of this.state
.
Ok, let's back up a little bit. React provides a method, known as ReactLink, to update this.state
on a component whenever the value of an <input>
field changes. This method is exposed by the convenient mixin React.addons.LinkedStateMixin
, which essentially just binds the onChange
event handler of the <input>
field to the this.setState()
function.
This is great, especially when creating a component with multiple input fields, but it starts to fall apart if you want to use deeply-nested objects inside this.state
of your component.
In that case, Facebook recomments using their ImmutableJS library to create immutable data structures, and use those as properties on this.state
.
The upside of using immutable data structures is that the shallow update we get with this.setState()
still works, and we can use React.addons.PureRenderMixin
to get a boost in performance without any expensive deep equality checks.
This library provides an alternative version of React.addons.LinkedStateMixin
that will let you "link" the value of your <input>
with an ImmutableJS data strucutre.
So you can take advantage of all the good Immutable, nested data structure stuff we just talked about while still having the sugary, easy-to-use syntax of LinkedStateMixin
.
First, install it with npm install --save reactlink-immutable
.
Then, just use it like you normally would with LinkedStateMixin
; except pass an array of keys instead of a string.
var LinkedImmutableStateMixin = require('reactlink-immutable');
var Map = require('immutable').Map;
var WithImmutableLink = React.createClass({
mixins: [LinkedImmutableStateMixin],
getInitialState: function() {
return { dog: Map({name: 'Sparky', kind: 'Lab'}) };
},
render: function() {
return (
<form>
<input type="text" valueLink={this.linkImmutableState(['dog', 'name'])} />
<input type="text" valueLink={this.linkImmutableState(['dog', 'kind'])} />
</form>
);
}
});
For convenience, a single string parameter is still supported for the key (rather than an array), which will make it behave like the standard this.linkState
method.
By default any non-primitive Immutable values (such as Immutable.List
or Immutable.Map
) you link to will be converted to their plain JS equivalent via the Immutable toJS()
function before passing them as value
. However, there is an option for linkImmutableState
that will disable this behavior if specified.
Ex: this.linkImmutableState(['myImmutable', 'myList'], { immutableValue: true })
will keep the myList
value as an Immutable.List
in the view instead of converting it to an Array
.
Also, by default any non-primitive, non-Immutable values (such as Array
or Object
) you link from your view state to will be converted to their Immutable equivalent via the Immutable fromJS()
function before passing them back to your state
. However, there is an option for linkImmutableState
that will disable this behavior if specified.
Ex: this.linkImmutableState(['myImmutable', 'myArray'], { mutableState: true })
will keep the myArray
value as an Array
in the state instead of converting it to an Immutable.List
.
- Author: David Idol
- License: MIT