Cycle-React
An RxJS functional interface
to Facebook's React.
Cycle-React allows users to write React
applications in functional style and represents their UIs as Observables.
In addition, Cycle-React is immutable and uses
PureRenderMixin
internally by default.
Additionally, Cycle-React is also a React-style implementation of a beautiful
framework called Cycle.js.
Installing
npm install cycle-react
Example
let Cycle = require('cycle-react');
let React = require('react');
function computer(interactions) {
return interactions.get('OnNameChanged')
.map(ev => ev.target.value)
.startWith('')
.map(name =>
<div>
<label>Name:</label>
<input type="text" onChange={interactions.listener('OnNameChanged')} />
<hr />
<h1>Hello {name}</h1>
</div>
);
}
Cycle.applyToDOM('.js-container', computer);
The input of the computer
is interactions
, a collection containing all
user interaction events happening on the user-defined event handlers on the DOM,
which you can query using interactions.get(eventName)
. And the event handler
can be defined by interactions.listener(eventName)
.
The output of the computer
is Observable<ReactElement>
(a reactive sequence of elements, in other words, view).
Function applyToDOM
subscribes that Observable of elements and renders the
elements to DOM, by using React.createClass
and React.render
internally.
Notice that although React.createClass
is mentioned here, you don't have to
use it. That's why Cycle-React was made. We took functions over classes
and mutable states.
You can learn more about the concept behind applyToDOM
and Cycle
from
André's amazing presentation:
"What if the user was a function?"
React component example
let Cycle = require('cycle-react');
let React = require('react');
let Rx = Cycle.Rx;
let Counter = Cycle.component('Counter', function (interactions, props) {
return props.get('counter').map(counter =>
<h3>Seconds Elapsed: {counter}</h3>
);
});
let Timer = Cycle.component('Timer', function () {
return Rx.Observable.interval(1000).map(i =>
<Counter counter={i} />
);
});
Cycle.applyToDOM('.js-container', Timer);
Learn more
Cycle-React is a React-style implementation of Cycle.js, so we have the same
concept of handling user interactions. Learn more on:
http://cycle.js.org/dialogue.html
In addition, we're working on the documentation site for Cycle-React with more
useful examples, too. Stay tuned!
Cycle.js Driver
Cycle.js (not Cycle-React) has the
driver architecture to externalize the
side-effects. Cycle Web, for example, is a driver externalizes DOM environment.
And Cycle-React provides a DOM driver (powered by React, of course)
for Cycle.js, too.
Details can be found at
"Using Cycle-React's DOM driver for Cycle.js".
FAQ
Can I use Cycle-React with Flux (e.g. redux)
Absolutely. Since Cycle-React's component
creates native React components,
there's nothing stopping you from using Flux architecture.
HOWEVER, we don't really recommend to use Flux when you already had Rx or
other event stream libraries at your disposal. Instead, we recommend the MVI
architecture which also achieves unidirectional data flow. See
"Reactive MVC and the Virtual DOM"
and "Good bye Flux, welcome Bacon/Rx?"
for more details.
Yes. And no extra configuration needed.
Example
Can I use Cycle-React with other React components and libraries?
Yes. You can also integrate Cycle-React with your current React apps. Because
component
creates the native React component for you.
Examples for integrating Cycle-React with other libraries are work in progress.
Meanwhile, See "Working with React"
for guidelines.
Run examples
npm run examples
starts an HTTP server that shows examples
- Ask "how do I...?" questions in Cycle-React's Gitter:
- Propose and discuss significant changes as a GitHub issues
License
The MIT License
1.0.1
MAJOR RELEASE: 1.0.1 is the stable version of Cycle-React.
Add feature: props.getAll()
returns the Observable of the whole properties object
[#10]
Alternatively, you can use props.get('*')
or simply props
for the exact same effect.
Breaking change: props.get(propertyName)
uses (x === y) comparison instead of
deep-equal comparison for the target property
Use props.get('*')
or props
if you have changes inside a nested object.
Alternatively, you can provide the customized comparer by
props.get(name, (x, y) => {})
Breaking change: renderAsHTML
has been removed
Use React.renderToString
with Cycle.component
instead.
Examples can be found at test/node/html-render.js
and examples/isomorphic
.
Breaking change: The h
hyperscript helper has been removed [#11]
Breaking change: Interactions API no longer uses selector for querying events
[#8, #12]
The selector API cannot handle both Cycle-React components and other React
components that use event handlers. We want to keep the compatibility with
the original React while not confusing developers. Therefore, the selector API
has been removed in favor of event handler API.
Information of the new interactions API can be found at docs/interactions.md
The migration guide can be found below.
Breaking change: on
prefix is no longer appended to event handlers for
Cycle-React components
Breaking change: Event detail is no longer wrapped by CustomEvent
Breaking change: The option "noDOMDispatchEvent" has been removed since
Cycle-React no longer dispatches events from DOM right now
BEFORE
// Component:
let MyComponent = Cycle.component('MyComponent', function (interactions, props) {
let vtree$ = interactions.get('.myinput', 'change')
.map(ev => ev.target.value)
.startWith('')
.map(name =>
<div>
<input className="myinput" type="text" />
<h1>Hello {name}</h1>
</div>
);
return {
view: vtree$,
events: {
myComponentTick: Rx.Observable.interval(1000)
}
};
});
// Intentions:
interactions.subject('tick').map(ev => ev.detail);
// View:
<MyComponent onMyComponentTick={interactions.subject('tick').onEvent} />
AFTER
// Component:
let MyComponent = Cycle.component('MyComponent', function (interactions, props) {
// You must use `get` to query events
// and use `listener` to create event handlers.
let vtree$ = interactions.get('OnMyInputChange')
.map(ev => ev.target.value)
.startWith('')
.map(name =>
<div>
<input className="myinput" type="text"
onChange={interactions.listener('OnMyInputChange')} />
<h1>Hello {name}</h1>
</div>
);
return {
view: vtree$,
events: {
// The event handler is no longer auto-prefixed by "on"
onMyComponentTick: Rx.Observable.interval(1000)
}
};
});
// Intentions:
// Event arguments from Cycle-React components are no longer
// wrapped by CustomEvent.
interactions.get('tick').map(ev => ev);
// View:
// Use interactions.listener(name) to create event handler
<MyComponent onMyComponentTick={interactions.listener('tick')} />
Migration
- Append the "on" prefix to every event observable inside the events object
of the component
- Rewrite the code that used
interactions.get(selector, eventType)
by using
interactions.get(eventName)
and interactions.listener(eventName)
like the
example above - Replace
interactions.subject(name).onEvent
with interactions.listener(name)
- Replace
interactions.subject(name)
and interactions.getEventSubject(name)
with interactions.get(name)
- Replace
ev.detail
with ev