These tests can still be run in the browser using `grunt test --debug`.
This is a repeat of 42f8d155f8. For posterity, we
do this because Phantom has a problem with Object.freeze and the test runner
can't do __DEV__ right (because we get rid of that in the build step).
Let's start logging objects as maps for children. We may want to deprecate this
and replace it with ImmutableMap and Map data structures instead.
This should ideally be logged in the recursive function but since that loses the
scope of where these children are passed it's easier to start tracking them
here to get an idea of how frequently and where it's used.
While looking up a detail of how `transferPropsTo()` works I noticed that we never check `TransferStrategies.hasOwnProperty(thisKey)` when merging props, just `newProps.hasOwnProperty(thisKey)` and a truthy test for `TransferStrategies[thisKey]`. This means that if our `newProps` has keys like `toString`, `valueOf`, or `constructor` etc. set, we will pull these functions off `TransferStrategies` and invoke them when merging props. In most cases this will just result in a failure to merge and some code without side effects being run but in the case of `valueOf` it will actually generate an exception.
I'm thinking that setting up `this.refs` in `mountComponent` is better than `construct`. Followed the same pattern as `ReactComponent.Mixin` and nulling out
the value in `construct` and setting it to its initial value in `mountComponent`.
This bites people all of the time. Until we have a better solution, let's just make the error message more actionable (most people don't know how the DOM
gets unexpectedly mutated).
The component that gets passed into renderComponent isn't guaranteed to be the
instance that gets mounted. We want to clone the instance.
Unit tests need to reason about the mounted instance. The first code mod changes:
ReactTestUtils.renderIntoDocument(<identifier>)
into
<identifier> = ReactTestUtils.renderIntoDocument(<identifier>)
Using this scripts:
scripts/bin/codemod -m -d ~/www --extensions js \
'^(\s*)ReactTestUtils\.renderIntoDocument\(\s*([$a-zA-Z0-9_]+)\s*\)' \
'\1\2 = ReactTestUtils.renderIntoDocument(\2)'
In the second case I do the same for React.renderComponent. However, there are
alot more unnecessary matches so I only codemod if the same identifier occurs
later in the file.
scripts/bin/codemod -m -d ~/www --extensions js \
'^(\s*)React.renderComponent\(\s*([$a-zA-Z0-9_]+)\s*?,(.*?\n?.*?\s\2\b)' \
'\1\2 = React.renderComponent(\2,\3'
And one more for ReactMount.renderComponent used by internals.
scripts/bin/codemod -m -d ~/www --extensions js \
'^(\s*)ReactMount.renderComponent\(\s*([$a-zA-Z0-9_]+)\s*?,(.*?\n?.*?\s\2\b)' \
'\1\2 = ReactMount.renderComponent(\2,\3'
This still matches many unnecessary cases where the second occurance of the
identifier is a redeclaration or comment. But this code mod doesn't hurt in
those cases.
Finally I have to do the same for:
this.<identifier> = React.renderComponent(this.<identifier>,
This is a common pattern for production code but not tests. Some of these call
sites will likely break when we move to true descriptors.
scripts/bin/codemod -m -d ~/www --extensions js \
'^(\s*)React.renderComponent\((\s*)this\.([$a-zA-Z0-9\_\.]+)\s*?,' \
'\1this.\3 = React.renderComponent(\2this.\3,'
We have unexpectedly had to shut Shirtstarter down, so it won't serve as a good React.js example any more unfortunately -- sorry for the documentation churn.
This is the first step towards descriptors. This will start cloning the
component when it's mounted instead of mounting the first instance.
This avoids an issue where a reference to the first instance can hang around
in props. Since a mounted component gets mutated, the descriptor changes.
We don't need to clone the props object itself. Mutating the shallow props
object of a child that's passed into you is already flawed. Those cases need to
use cloneWithProps. A props object is considered shallow frozen after it leaves
the render it was created in.
Optimizations and fix for JSXTransformer build.
Dropped dependency on emulation of Node.js native modules.
Added deamdify step for JSXTransformer build.
We found that the component would break if we set any statics with the
value 0. It turns out @chenglou already ran into this with
d71736b3ed but the statics code was copied
earlier, and still has this falsy check. Made the same change, updated
the unittest.
After we run `require('mock-modules').dumpCache()`, the object exported by
the `emptyObject` module will no longer be identical to previously
exported objects, so tests like `expect(component.refs).toBe(emptyObject)`
will fail.
Note that this behavior only manifests itself in tests, because of course
we do not call `dumpCache` in production code.
We could consider storing the `emptyObject` globally to thwart the effects
of `dumpCache`, but it's more idiomatic simply to re-`require` the latest
version of `emptyObject`.
If no refs are rendered, `this.refs` is undefined. This is bad since it deopts & is hard to look for. Instead we should make `this.refs` an immutable empty object.
This adds an instrumentation hook for logging so that we can monitor invalid API
usage before we're ready to issue a warning.
I took the opportunity to update some console.warns to use the warning module
instead. The remaining console.warns
will be replaced by the warning module after we've cleaned up the callsites.
When IE8 focuses a disabled item, it throws
This makes sure the we're not focusing the item during selection restoration/autofocus when the element's disabled.
There were these two lists of JSX tools at Complimentary Tools
and Tooling Integration, that were a bit out of sync with each other.
Bring them together and add a link to the former from the latter.
Dealing with immutable data is hard. This provides a simple helper (ported from the IG codebase) that makes dealing with immutable JSON data easier. Designed to be familiar for people who use MongoDB.
This is part of what Sebastian suggested. We require it into every component that explicitly needs it and inject it as a default mixin for composite components in
the browser environment. This change frees us up to inject everything in ReactComponent.
Most of the time this is what you want to do, so I've renamed what was Simulate to be SimulateNative.
Now Simulate.change does what you expect, so this fixes#517 and fixes#519.
grep -rl 'Copyright 2013 Facebook' static_upstream | xargs perl -pi -w -e s/Copyright 2013 Facebook/Copyright 2013-2014 Facebook/g;'
Not going to check in a script to do this since it will just change every year.
Closes#1006
Fixes#1124.
I didn't add `volume` because it requires more complicated logic to control properly and I didn't add `paused` because to set it we need to call play() or pause() -- perhaps a mutation method is appropriate.
Two improvements: make sure we set `done = true` when an error message is
received, so that the test output contains the error message instead of
eventually timing out and displaying nothing useful; and increase the
timeout for this particular test from 5000ms (the default) to 20000ms.
reverts 23ab30ff87 because the issue it fixed doesn't seem to be a problem
anymore. textContent should be better for more things anyway, as the
original 309a88bcf6 indicates. It should be faster because innerText
requires layout.
This also allows us to use strings with newlines in our rendered output
and have confidence that they will render the same on subsequent
re-renders. This is especially useful for es6-style backtick multi-line
strings. This will be more consistent as textContent is supported almost
everwhere so we won't have differing behavior between webkit and
firefox.
see https://github.com/facebook/react/issues/1080
ReactDefaultPerf:
* Show times as float instead of string. This means they're sortable.
* Add count columns to all types and average to exclusive time.
* Include mountComponent where updateComponent time is measured.
* Increment count on _renderValidatedComponent instead of update.
ReactDefaultPerfAnalysis:
* Return counts with all summaries.
Split the summary functions into a separate module, and add the ability to view a lot of all DOM operations. Removed DOM timing since it was incorrect. Will potentially replace with a
dropped frame counter in the future.
This logs DOM ops for a given reconcile. Based on which components rendered and which ones *actually* caused DOM updates we can find
opportunities to add shouldComponentUpdate() methods.
Inclusive time is still not that helpful w/o looking at what actually resulted in DOM ops. However, this is better than what we have today and will serve as a building block.
I blacklisted everything but composite components -- hopefully that's OK.
The key idea here is that you're always rendering `this.state.children`, not
`this.props.children`. When combined with `cloneWithProps()` this means we can
keep them in the DOM as long as we want. We add new children and reactively
update existing ones using `setState()` inside of `componentWillReceiveProps()`
so `this.state.children` always has the latest versions of components. Since we
may be keeping old components around that are no longer in
`this.props.children` we need a way to figure out where they should be inside
of the combined `this.state.children` list. `ReactTransitionChildMapping` does
this for us.
Based on that infrastructure we can build the interface we always wanted: enter
and leave lifecycle hooks.
When a component is added to the DOM, `componentWillEnter(callback)` gets
called. Call the callback when you're done animating and `componentDidEnter()`
will be called.
When a component is about to be removed from the DOM,
`componentWillLeave(callback)` gets called. Call the callback when you're done
animating and `componentDidLeave()` will be called and the component will
*actually* be removed from the DOM. It won't be removed until you call the
callback.
These also handle "concurrent" changes. If you "stack" enter/leaves of a single
component before the animation has completed, it will block out all of those
animations until the current animation completes, and then finally it will
animate 0 or 1 times to get itself into the desired current state. This is what
differentiates `componentWillEnter()` from `componentDidMount()`.
The next step would be to build `componentDidReorder()`.
I've built `ReactCSSTransitionGroup` which is identical to the old
`ReactTransitionGroup` and codemodded the callsites.
With #1021 and #1022, I believe this makes it so React never wraps user code in a try/catch. I left in the calls to ReactErrorUtils.guard because it sounds like FB code finds them useful.
This creates a membrane around the React component prototype. It warns if you
try to access properties on the component before it's unmounted. Before it's
mounted, it should be considered a descriptor and not an actual instance.
The workaround, for unknown types, is to access the constructor using
component.type which has static methods on it.
All of this is provided by the react package now, so there's no point in having
it available in multiple places. We *may* go back on that in the future for
shipping test utils, but for the time being, this is better for all.
Also added tests for PooledClass.
Noticed that some places use `ReactReconcileTransaction.release(transaction)`, when `transaction` might be of another class, say `ReactServerRenderingTransaction` (still a Github PR). This catches that.
If a transaction wrapper's closer throws (such as flushBatchedUpdates in ReactDefaultBatchingStrategy) then we still want to properly deinitialize the transaction by setting isInTransaction to false. Without this, we can't reuse the transaction object (in this case, all future batched updates would fail because nested transactions aren't allowed).
Removed uglification for separate files since it significantly slowed down build (browserify:min became 26 sec instead of 110, same for :addonsMin) while gave economy in ~70 bytes for min+gz version.
The documentation states that React.renderComponentToString
'uses a callback API to keep the API async', but the
implementation is actually synchronous. In order to maintain
this contract the callback should always be called
asynchronously or be change to a synchronous API.
As per the discussion of pull request 982, the API should
be changed to a synchronous one.
Recently learned that components passed into `React.renderComponent` may not be the ones actually mounted. Also learned that it returns the mounted component. Added some documentation describing this.
Number('.1') === 0.1, and react uses dot-prefixed keys
for children. Whoops. Nuke the non-numeric requirement, and just
check a regex. This seems performant enough in micro-benchmarks:
http://jsperf.com/numericlike
We've been able to use `querySelectorAll` in all the browsers that we
support for some time now, but we haven't been able to test code that uses
it in the older version of `jsdom` that we were using, until recently.
Besides the general goal of modernizing our code, the impetus for this
specific change is that I'm trying to support testing without having to
render nodes into an actual document. The `.getElementsByName` method is
only defined on `document` and only works if the nodes you care about are
contained by the document.
On the other hand, `querySelectorAll` works on any DOM node, and allows a
more precise selection of just the `<input type="radio">` elements that
have the appropriate name.
IE8's implementation of `querySelectorAll` supports attribute-based
selectors, which is all we need here.
Little-known fact: instead of writing copies of compiled module files to
build/modules/, the bin/jsx-internal script actually just makes hard links
to the master versions of files in the .module-cache/, so re-populating
build/modules/ is very inexpensive.
Closes#856.
Rethrowing errors makes debugging harder. This makes it so that an exception in a render method can be caught using the purple stop sign (or the blue one, of course) in Chrome.
This codemods to shim any old-style JSX whitespace so that it renders the same as before.
Basically it sticks explicit `{' '}` spaces in where spaces are no longer implicit.
`cloneWithProps` uses `ReactPropTransferer`, which ignores the `key`
prop. See https://github.com/facebook/react/pull/713
However, this is not the case with `cloneWithProps` because when someone
is cloning a component and provides a key, they mean for the clone to
take it.
We've talked about this perf optimization for a while now. This prevents us from re-reconciling components that are above the component being
reconciled in the owner hierarchy.
See [Commoner's README.md](
https://github.com/benjamn/commoner#generating-multiple-files-from-one-source-module)
for further explanation of the new functionality.
Among other potential benefits, this upgrade allows us to generate source
maps as standalone files rather than appending them inline to every
compiled module file under `build/modules/` (see #833).
When React moved to attaching top-level event listeners on-demand, not all of the dependencies for `ChangeEventPlugin` were set. This led to `onChange` events not firing under certain circumstances. For example, listening to `onChange` on a checkbox will not work because it relies on `onClick` (unless something else on the page was listening to `onClick`).
The intention of the `npm-react/**/*` rule was to copy recursively but it would have flattened any nested directory structure. I changed the `build/modules` rule to copy recursively as well, which is necessary for `ReactTestUtils` to be able to require `test/mock-modules.js` successfully. (`ReactTestUtils` isn't included in a clean `npm-react` build currently but it will be in the future.)
This also makes running ART tests more practical.
It's only used here, so let's just inline this and get rid of the additional module.
Also it will make people like this guy happy: https://github.com/facebook/react/issues/900
(of course he might be even more happy if he wasn't using MS TFS....but that's a much bigger diff, and not one I can write...)
This diff introduces PropType.shape which lets you type an object. PropType.object was already defined and since it isn't a function I couldn't really overload the meaning to also accept a type list. Instead of doing hackery, I decided to name it `shape`.
An example where this could be used is style:
```
propTypes: {
style: PropTypes.shape({
color: PropStyle.string,
fontSize: PropTypes.number
})
}
```
Fixes#208. If you attempt a state update with a bad state then the render will fail (and the DOM won't change) but if you switch back to a valid state later then it'll rerender properly.
This is an alternative, less-invasive, fix for #891.
Test Plan:
On http://jsbin.com/OqOJidIQ/2/edit, got timings like
[75, 56, 30, 36, 27, 27, 28, 32, 27, 27, 28, 31]
instead of the old
[75, 729, 46, 32, 28, 34, 26, 27, 27, 30, 26, 26].
I also added a counter to getID and saw it was called 3014 times instead of the old 636264. (3014 is the number of nodes (3000) plus 3 calls that happen for the initial render and 1 for each of the 11 renders after that.)
add the ability for React propTypes to accept an `any` type: `someProp: React.PropTypes.any`.
This is more useful when combined with `.isRequired`, to enforce that _something_ is passed:
`someProp: React.PropTypes.any.isRequired`
Input elements of type `checkbox`, `hidden`, or `radio` can have a `value` without `onChange`. Also, if the input is `disabled`, who cares that it doesn't have an `onChange`?
This is a follow-up to #803.
In jsdom (used for internal testing), `<iframe>` does not properly create a default document. This makes the `EnterLeaveEventPlugin` tests work for jsdom, too.
Open source does not need this because it uses PhantomJS.
In b0431a5 I added the check in the wrong place which could cause the warning to be shown because of key changes rather than owner changes like the warning suggests.
This test is expected to throw but because of ReactErrorUtils.guard
which uses console.error in __DEV__ it also logged the invariant error
to the console. This change fixes it by temporarily stubbing out
console.error.
Fixes#531
Final part of server rendering cleanup. We should only support full-page rendering when server rendering is involved since
otherwise it's slow and can crash browsers when you start adding and removing document roots. This diff removes the magic
innerHTML code (since that will be handled by the server rendering piece) and adds the right assertions and errors.
Because there's no longer a dangerous of accidentally nuking the whole page, I removed allowFullPageRender which is yet another
internal we no longer need to expose.
These are dangerous from a cross-browser perspective. I think supporting efficient reactive updates will be prohibitively
expensive and we'll never prioritize it. Instead of killing this capability entirely, let's just throw on the dangerous cases.
There will be a few follow-up diffs
This ensures we don't add displayName in the transform if it's already been
defined. This is especially important when in strict mode, where duplicate
properties in an object is an exception.
Use the `clipboardData` object available on `window`, if it's not available on the event object. This allows us to support including the `clipboardData` in cut/copy/paste events in IE.
If you're writing a test that involves a mocked component that normally
returns a `<li>` tag from its `render` method as the root element, mocking
it with a dummy `<div>` probably won't work, so you'll want to set
MyListItemComponent.mockTagName = 'li';
The change to the `.mockImplementation` line makes sense because
`ConvenienceConstructor` is more or less synonymous (for these purposes)
with the wrapper that was previously used:
function() {
// This `this` used to be `null`, technically, but
// ConvenienceConstructor doesn't pay attention to `this` anyway.
return ConvenienceConstructor.apply(this, arguments);
}
This had a higher probability of collision than originally thought (bad math). This makes the strategy injectable and provies a
no-collision version on the client and an unlikely-to-collide version on the server.
what if you want to change the props of a child? This is my first attempt which lets you clone a child and transfer some custom props to it.
There is a fundamental issue with refs here. Since the component is cloned the ref will be broken. And since we can clone multiple times, it might not make sense to support repairing refs.
Fixes#767. This essentially reverts 738de8c.
We could store some sort of flag to silence the console error here but since we've made significant improvements in markup wrapping, this error is fairly rare now. We'll also have validation of node structure soon in #735.
- Add html5shiv so that HTML5 elements like header, footer, etc can be styled
- Remove a couple uses of :first-child/:last-child which IE8 doesn't support
Fixes#708.
Test Plan:
In IE9, tested a controlled text input with the event handler on a containing element, as in the fiddle linked in the original issue. Also tested a controlled radio button as the logic there differs within ReactDOMInput. In both cases, I was able to interact with the controls.
Now when a `key` prop appears, its value is always honored. This means that in the root component or as an only child, changing key will cause remounting; in a `children` object, the `key` prop will be joined with the object key to form a two-part key.
Fixes#590.
It changed React Playground to add a required props but unfortunately didn't update the call sites of the front-page. I don't think it should be required so I'm just making it optional and providing the correct default value.
Test Plan:
- Open the front page and make sure examples are working
- Open /react/jsx-compiler.html and make sure it is working
- Open /react/html-jsx.html and make sure it is working
Since we can use props to pass React Components, we should have a better way of validating these props than just `object`. Having a prop type `component` will allow us to safely assume that the passed prop IS a component.
This is a follow-up the to previous commit and does two things:
- Moves `ReactMount.ATTR_NAME` to `DOMProperty.ID_ATTRIBUTE_NAME`.
- Adds `DOMPropertyOperations.createMarkupForID` and uses it.
We have this really nice method for safely creating markup for an HTML
attribute, `DOMPropertyOperations.createMarkupForProperty(...)`. Let's
use it to create the ID attribute markup, too.
These should be included so that anybody can build and update the docs
with as little confusion as possible.
I've left the directory in .gitignore so additions need to be
intentional as part of a release.
This reduces the time taken by `grunt populist:test` from 7s to 550ms,
which should make @spicyj especially happy.
Relevant commits from the `populist` and `ast-types` repositories:
9863ad16c0dabef2a4ac
This fixes merging of `propTypes`, `contextTypes`, and `childContextTypes` so that we actually merge (instead of only taking the component or last mixin).
Using props to initialize state is completely fine; the issue is using state as a "cache" for values calculated based off of props. This title makes it more clear.
Chrome gives the warnings
```
body.scrollLeft is deprecated in strict mode. Please use 'documentElement.scrollLeft' if in strict mode and 'body.scrollLeft' only if in quirks mode.
body.scrollTop is deprecated in strict mode. Please use 'documentElement.scrollTop' if in strict mode and 'body.scrollTop' only if in quirks mode.
```
the first time getUnboundedScrollPosition is invoked. This fixes it. (All modern browsers support `pageYOffset`; IE 8 doesn't but works properly with `document.documentElement.scrollTop` except in quirks mode which React doesn't support.)
In the case of having an animated node which is, after the leave-transition has been activated, then re-added in a render call causes React to 'break'. This is especially noticeable if you spam to removal and re-addition of an item in a ReactTransitionGroup.
This fix simply stops the leave transition and restarts the enter transition.
This reverts https://github.com/facebook/react/pull/576
This approach mutates the default props for the instance on each update,
which causes incorrect behavior. discussed with @balpert. can look into
cloning but this unbreaks.
This leaves statics as a way to define static methods and properties
that will be accessible on the return value of `React.createClass`
without changing the current spec.
It is valuable to know when the number of children in a TransitionGroup is going
to increase or decrease, since we might want to apply extra animations.
For instance, when used with overflow:auto, we might want to apply different css
based on it overflowing or not - to do this we need to calculate this after new
nodes has entered and after nodes has been removed.
This moves the static properties off of the root object and into
a 'statics' property. Then they are made available on the constructor so
they can be used directly and in mixins.
Pull request #526 updated the behavior of vendor/constants.js without
changing any source files or the bin/jsx-internal script, so files that
should have been rebuilt (like utils/__tests__/ImmutableObject-test.js)
were not automatically rebuilt (unless you knew to do `grunt clean` or
`rm -rf .module-cache` manually).
This commit allows us to bump a version number when we know the transform
toolchain has been altered in a way that will not be visible to
commoner/jsx.
With this convention, if we reset to an older revision (e.g. during a git
bisect) and the appropriate cached module files are still in the
.module-cache/, they can be used without rebuilding. That's why I prefer
this approach to just deleting the .module-cache/.
Closes#104.
Closes#496.
Closes#530.
Summary:
e.g.
propTypes: {
foo: React.PropTypes.oneOfType([
React.PropTypes.string,
React.PropTypes.number
]);
}
to do this, I exposed a `.weak` chainable validator that returns instead of throws, e.g.
React.PropTypes.string.isRequired.weak
React.PropTypes.string.weak
which returns true or false. Technically, `React.PropTypes.string.weak.isRequired` also exists, but `oneOfType` will never call it. Might be useful to people creating custom validators though.
Since we use keyMirror() and invariant() messages are only shown in __DEV__, we don't have to do manual constant->string translation. Also fixes a few
undefined keys that just happened to work before.
It doesn’t make much sense to generate a random key for each todo render, because it will re-draw all todo’s DOM nodes on each model change. I changed it to the unique identifier ``todo.cid`` already supplied by the backbone model.
benjamn/commoner#44 fixed commoner to work on Windows when module path relativization isn't used; with this, the `jsx` binary should work properly on Windows (though `jsx-internal` still won't).
Fixes#316, fixes#391, fixes#567.
As an added bonus, the jasmine web interface now groups tests by file.
Test Plan:
grunt test passes on b2507066, the parent of 566f8b2e (which committed a workaround for buggy module mocking).
We can already access the DOM node using `this.getDOMNode()`. Passing it as an argument was a bad decision.
Previous API:
```
componentDidMount(DOMElement rootNode)
componentDidUpdate(object prevProps, object prevState, object prevContext, DOMElement rootNode)
```
Next API:
```
componentDidMount()
componentDidUpdate(object prevProps, object prevState, object prevContext)
```
callbacks like shouldComponentUpdate, componentDidUpdate, etc. were getting the full, unsanitized context, instead of the one that's been filtered down to only the fields allowed to be visible by contextTypes.
Context is adding another argument that shifts all of them by one. Since we can already use this.getDOMNode(), it doesn't really make sense to pass it as an argument to that function.
Depends on #575; fixes#570. Now we'll be in trouble if someone tries to share objects between calls to getDefaultProps but that was already true of getInitialState and I haven't heard any complaints there.
This is the same number of allocations as before; we're just copying props in the other direction. (In any case, the copy happens only on mount and there are a couple dozen costlier things we're doing already at that time.)
This module-level mock() seems to have been interfering with other tests (26 specs failing). We don't have any other tests that do a module-level mock() so I'm going to assume it isn't supported in the open-source test runner right now. I changed it so only ReactEventEmitter.handleTopLevel is mocked; doing so made ReactEventEmitter complain that TopLevelCallbackCreator wasn't defined so I switched the ReactMount references to use React directly so that ReactDefaultInjection would kick in properly.
With this, all the tests pass.
...without preventing clicks on other things.
Just use an `<a name="...">` tag that doesn't take up any space to make sure that we're not covering up something else.
For whatever reason, doing `position: relative; top: -$navHeight;` doesn't work and causes the anchor target not to be moved up. This solution works in both Chrome and Firefox.
When events are captured, the nearest React-rendered ancestor is found and events are propagated to its tree. This causes issues when components are nested as only the innermost component receives the events.
This change modifies this behaviour so events propagate all the way up the DOM hierarchy. To reduce the performance cost, this DOM traversal is only done if the component is actually nested (determined by the `containerIsNested` map which is lazily initialised).
Summary:
adds `this.context` which you can think of as implicit props, which are passed automatically down the //ownership// hierarchy.
Contexts should be used sparingly, since they essentially allow components to communicate with descendants (in the ownership sense, not parenthood sense), which is not usually a good idea. You probably would only use contexts in places where you'd normally use a global, but contexts allow you to override them for certain view subtrees which you can't do with globals.
The context starts out `null`:
var RootComponent = React.createClass({
render: function() {
// this.context === null
}
});
You should **never** mutate the context directly, just like props and state.
You can change the context of your children (the ones you own, not `this.props.children` or via other props) using the new `withContext` method on `React`:
var RootComponent = React.createClass({
render: function() {
// this.context === null
var children = React.withContext({foo: 'a', bar: 'b'}, () => (
// In ChildComponent#render, this.context === {foo: 'a', bar: 'b'}
<ChildComponent />
));
// this.context === null
}
});
Contexts are merged, so a component can override its owner's context **for its children**:
var ChildComponent = React.createClass({
render: function() {
// this.context === {foo: 'a', bar: 'b'} (for the caller above)
var children = React.withContext({foo: 'c'},() => (
// In GrandchildComponent#render,
// this.context === {foo: 'c', bar: 'b'}
<GrandchildComponent />
));
// this.context === {foo: 'a', bar: 'b'}
}
});
Reported on Twitter by AirBnb (who are integrating React into their open-source JS framework). They made a mistake and passed a string in as the
component. We should have a better error message for that.
This renames receiveProps and changes it to take the next component to copy props from instead of just the props. That is,
component.receiveComponent(nextComponent, transaction)
instead of
component.receiveProps(nextComponent.props, transaction)
This is a precursor to adding contexts, which will also need to get propagated just like props. This change allows ReactCompositeComponent to override `receiveProps` and do something like
this._pendingContext = nextComponent.context;
Most notably, this new style of transformation gives us access to
this.parent.node, which allows us to avoid replacing identifiers that are
not actually free variables, such as member expression properties.
Closes#496.
Two of your tests were failing because of commit
1e71df5399
I fixed them by:
1) Using jasmine's spyOn in ReactCompositeComponentError-test.js
2) Inverting the function wrapping in the above commit.
Godspeed.
- Overview of add-ons for the add-ons page.
- Better title for `ReactLink`.
- Nicer code format for classSet example.
- Better explanation for `classSet`.
When we determine whether a React component should be updated (as opposed to destroyed or replaced), we currently only look at whether they share the same constructor. This adds a check for whether they share the same owner component.
I've also consolidated this logic (I cannot believe this was not already done).
dataType was unnecessary; mimeType was both unnecessary and wrong in this case. Also removed an unnecessary bind and changed pollInterval to 2000 ms for consistency with https://github.com/petehunt/react-tutorial (faster is nicer if you actually try it out!).
IE 11 no longer supports the legacy document.selection API.
Their implementation of window.getSelection() doesn't support
the extend() method, which we were relying on.
If the selection is RTL and selection extend is missing, then just
flip the selection.
The initial thought was that an opacity animation from 0.01 to 1 causes trouble on some browser. But after testing on opera 12.15, ff 23, ie 10, chrome 30, desktop/mobile safari 7 and chrome android I confirm this works.
Newer versions of WebKit and Blink will support both `document.body.scrollTop` and `document.documentElement.scrollTop`. Therefore, implementing cross-browser compatibility by summing the two will no longer work.
This changes React to use `getUnboundedScrollPosition` so we get the fix and consistency in one change!
See: https://rniwa.com/2013-10-29/web-compatibility-story-of-scrolltop-and-scrollleft/
- No need to mention React, you know you're working with it =).
- Wrap code elements in back ticks, so that they get the "box" styling for md.
- You'd want the snippet to work inside the live editor, so you need to `renderComponent`. As per wiki specification, the DOM element on which to mount is `mountNode`, just like on the front page.
- Don't forget the JSX pragma, or else your `render` fails.
- Nitpick: empty line after the end of md.
- No need for jQuery reference since
1. The general mood around React is that you don't need jQuery.
2. The syntax' still clear without jQuery.
3. We're doing a jQuery integration entry =).
- `getInitialState` was absent.
- You don't need `componentWillMount` here. fetch them in `getInitialState`.
- The non-spoken convention seems to call the event handler `"handle" + eventName`. So `handleResize` clearly indicates it's a `resize` handler while `updateDimensions` might do something else. This latter name might actually be better under circumstances where you use call the method directly somewhere, but since we removed the only direct usage in `componentWillMount` this is fine.
- Went OCD again and tried to keep the code short. `width` is enough of a demo. Removed `height`.
- Distinguish between DOM events and React events. Wish we go full React events in a near future.
When a ReactDOMComponent is created with the property `disabled: true` subsequently setting the property to `disabled: false` the HTML attribute `disabled="true"` was being left in the DOM.
If we are to unmount a component mounted into a document element we should
unmount it from document.documentElement and not from document.firstChild which
is a doctype element in this specific case.
Fixes#447.
We do this by moving the actual anchored element up in the page without moving the actual text. (Apple uses a similar trick in their framed docs.) Now this looks a bit sillier on smaller screens but it's better overall.
Currently, default props as defined by `getDefaultProps` are only used if a prop is not specified (using `X in Y` check).
However, this makes it difficult for composing components to pass along the state of not being defined, for example:
render: function() {
// If `this.props.someProp` is not set, `InnerThing` should use the default value.
return <InnerThing someProp={this.props.someProp} />;
}
This changes the requirement for falling back to the default value to an undefined check (using `typeof X === 'undefined'`).
Remember that one time I wrote release notes and said:
> This is a breaking change - if you were using class, you must change
> this to className or your components will be visually broken.
Good thing I didn't listen to myself!
We had something that did the same sort of protection. The module
differs slightly (returns document.body instead of undefined) but
looking at the callers, that should be ok.
Allow more than strings and numbers to be used as attributes for DOM
nodes. This removes the special casing for `0` and `false` that was
being used in ReactDOMInput and ReactDOMTextarea.
Now we will just `toString` any object we try to insert into a DOM.
Closes#422, #372, #302
`jsdom` behavers differently than browsers here and we should ensure
that we are consistent. Browsers should be (and are) converting to
a string first, while `jsdom` doesn't.
Forcing wrapping seems necessary here: I compared a <circle> created within a <div> with a <circle> created inside an <svg> and they appear to have exactly the same properties with the exception of .parentNode (and .parentElement), yet the former refuses to show up when appended to an <svg> element. As such, I can't find any useful way to write a unit test (testing getMarkupWrap's output doesn't seem particularly useful to me).
Fixes#311.
Test Plan:
With a component that adds a <circle> after mounting (such as http://jsfiddle.net/spicyj/hxFVe/), verify that the circle appears in both Chrome and IE9.
The injection was only evaluated when ReactCompositeComponent was first loaded.
This made it impossible to inject a custom measure and the injection pointless.
Test that React loads properly in a web worker.
Most of this code is open source-only, so I think it's safe to merge without figuring out how to translate it upstream first.
This creates a new standalone build which should have everything the
default build has, plus a little extra. This is not a sustainable long
term solution (we shouldn't make people choose like this) but it fixes
the problem we have in the short term.
This also removes the terrible react-transitions build. This is better
anway.
Fixes#369
There were 2 issues:
I was reusing event outside the original event handler (activeNativeEvent).
This is a bad idea. I've changed deferred dispatch to have an empty object
as the nativeEvent.
I didn't handle inputs without .selectionStart (e.g. file inputs). I extracted
a input type check from ChangeEventPlugin and reuse it here.
This is dangerous because it means that data is flowing into the component from two components, only one of which is the actual "owner". While we may be able to figure out how to
support this someday, let's be strict and prevent it for now.
Polyfill 'onSelect' behavior for React.
Use non-standard 'selectionchange' event rather than 'select' event.
This allows us to fire the event when user moves the cursor via arrow
keys, and not just when they select multiple chars.
Add methods to ReactDOMSelection to make getting current selection
easier, so we can do a fast check for change without having to
calculate char offsets for selection start and end.
Exposing the _renderedChildren property before all the children are fully
mounted. This allows us to debug a partially mounted tree when the debugger
has a breakpoint in the one of the mounting children.
This only has a functional difference in the case where mounting throws. This
will end up not mounting the component anyway. Any remounting shouldn't be
affected by this change.
Setting the `eventName` attribute of an element to the empty string is not
enough to cause `typeof element[eventName] === 'function'` in jsdom. The
attribute value actually has to look like a function body.
If we reconcile components higher in the hierarchy they will likely reconcile components lower in the
hierarchy. If we sort by depth then when we reach those components there will be no more pending state or
props and it will no op.
The spec for eval (http://es5.github.io/x15.1.html#x15.1.2.1) says "If Type(x) is not String, return x." and that's exactly what's happening here -- it gets {code: ...} and does nothing.
This introduces `ReactLink` which is a super lightweight way to do two-way binding for React.
If you want to use a controlled form input today, it's a lot of lines of code:
http://jsfiddle.net/T3z3v/
Look how many times `name` is repeated in there. And you have to remember to wire up event handles and pass the right state and
right event handler for *each* form field. It's really annoying.
With ReactLink, you can "link" a form value to a state field. It's just some simple sugar around the value prop/onChange
convention:
https://gist.github.com/petehunt/6689857
Ah, much nicer! And requires very little core changes or extra bytes. `ReactLink` just wraps the current value and "request
change" handler into a little object and provides some sugar to create some from composite component state.
Move compositionstart/compositionend to a new event plugin.
Add a polyfill that listens to key and mouse events and uses selection to
determine which text has changed.
Add a DOM based selection module. This can both be used on its own and
in ReactInputSelection where our current implementation is lacking.
There is still some inconsistency with how IE and modern browsers
handle block nodes. Should be OK if we are just getting and setting
and not trying to set selection based on character offsets.
This gives markdown headers an id so that we can link directly to
sections of our docs. This is better than the alternative of adding them
all ourselves.
In the IE code path the method assumed that the input.value property
was non-null. A quick fix is to use either value or innerText; which means
the same code can be shared for textarea and contentEditable components.
The code is slightly buggy because the range.parentElement() !== input check
will fail for contentEditable components when the focus within a deep DOM tree.
The selection object doesn't always have ranges. In Chrome the
selection is not updated before 'focus' event handlers are fired. See
http://jsfiddle.net/t4DYA/ for example.
The selection will have rangeCount of 0 and calling getRangeAt(0) will
throw error "Uncaught IndexSizeError: Index or size was negative, or greater
than the allowed value."
This isn't really ideal, but it makes it so that people managing to
build with @providesModule still get a consistent experience (since this
is what gets packed client-side with react-page-middleware anyway).
I am unsure how this was ever supposed to work, as testDocument is guaranteed to be undefined at that point since beforeEach doesn't run synchronously. (I don't think there's any way to have beforeEach halt the tests.)
Previously, setting textarea `value` to number 0 is treated as if `value` wasn't set at all (thus the textarea is cleared from 0 to '' upon `onChange`). `false` also renders as `"false"` instead of `""` for both `defaultValue` and `value`, on textarea _and_ input.
Created a .mailmap file with all of the associations, then used
git + perl to create the AUTHORS file. In theory these should all get
picked up by npm.
I used ABC order so it would remain unbiased and automatable. I wish we
could go back and fill out the history or at least fix the commits we
have from CommitSyncScript, but oh well.
This also includes the script I used to automate this process in the
future.
It seems like the `form="pluto"` was throwing it off and making the input live outside the form it should have been contained in, causing it to uncheck A. I added it intending to test the form attribute but ended up not needing it so removing it should be fine. (The tests were passing in phantomjs since it doesn't support the `form` attribute and simply ignored it.)
Test Plan:
grunt test; grunt test --debug
Add clipboard events to React.
For forms, these shouldn't really be necessary -- the onChange event should handle deletions and insertions. For contenteditables, however, we need to be able to access clipboard data.
getConfig needs to be a function because grunt.config.data.pkg.version isn't available at the time that grunt/config/jsx/jsx.js is required.
Test Plan:
grunt build, grunt lint, grunt test all work. After building, both react.js and react.min.js contain the version number.
Closes#271.
All three of these files are DOM-specific so it should be fine to use window. (ReactEventTopLevelCallback isn't obviously DOM-specific but it calls getEventTarget which is so I think we're fine here.)
Test Plan:
grunt test, tried events in a real browser and they seemed to work still.
Jordan warned (and StackOverflow confirmed) that IE8 doesn't respect HTML
comment nodes when setting `.innerHTML`:
http://stackoverflow.com/questions/15006001/inserting-a-comment-in-innerhtml
The virtue of the comment strategy was that the parser did all the work of
maintaining the boundaries between markup chunks, using comments as the
boundary markers. The new strategy (of tagging the first node with a
special attribute) has a similar virtue, since the parser should preserve
that attribute only for the nodes we care about, and any rendered nodes
that do not have the attribute can be ignored (and complained about by
`console.error`).
Logging every unknown property got very noisy when combined with use of `transferPropsTo`. I knew this would be a potential issue initially but decided it was worth it. Others disagreed and it's resulting in some confusion.
This changes the logging to ensure that we have a potential correction, so only DOMish properties should result in warnings.
Sencha says that separating big components into their own iframes was important for performance:
http://www.sencha.com/blog/the-making-of-fastbook-an-html5-love-story.
Today the only thing stopping us is that events don't bubble to our events system from an iframe. This diff
looks at the owning document of the container and adds top-level listeners to it. It should not change
existing behavior and should improve our support for this.
This builds `ReactTransitionGroup` with it's own copy of `React`, which
it total clownshoes. This should be technically usable, but definitely
should not be used in any production environment.
Fixed:
- New todo not submitting correctly (page refreshes. `preventDefault`
wasn't there.
- Old checked todo being removed will leave the checkmark on the next
todo replacing its position.
- Cannot change todo (`value`'s now a controlled field).
- `autofocus` (should be `autoFocus`, how ironic given the current
situation) on new todo input isn't working. Switched to manual
`focus()` in `componentDidMount` for now.
- More consistent breathing space between lines.
- Gutter at 80.
Added:
- Use todomvc-common base.css. The old one had to change ids to
classes. No longer necessary.
- Give `cx` a better name and move it in `Utils`.
- Trim input upon finishing edit.
- Remove todo if the new edited value is empty.
- Submit edited todo value on input blur.
- README to explain the existence of this example. Being able to
maintain a non-compilant version allows nice deviations from the
todomvc specs, such as animations, in the future.
We will continue using `bin/jsx-internal`, well, internally.
Note that this version no longer respects `@providesModule`, and it
doesn't do anything special with constants like `__DEV__`, so we can no
longer get to claim that `bin/jsx` can be used to build the core.
I'm happy about this, personally, because it demonstrates the flexibility
of Commoner.
This was apparently only partially supported. We had issues initially mounting if there was no HTML present and
also had issues if we had to update HTML that was already there. This diff fixes all of these cases and has
tests to prove it. NOTE: I removed a test that was actually erroneous. My bad.
HTML comment nodes are now interspersed in the original markup list so
that we can tell which chunks of markup rendered as more or less than one
node, and give a more helpful error message in that case.
Regardless of how many nodes were rendered, we only take the first one. If
zero nodes were rendered, then `resultList` will contain `null` at the
corresponding position.
If we decide to revisit the idea of using document fragments, it will be
very easy to handle the `!== 1` case by returning a document fragment.
This introduces <ReactTransitionGroup>, a component that works a lot
like Angular's ng-animate.
The problem we're currently facing is twofold:
1. We don't really have a great convention surrounding CSS transitions
in React
2. (harder) we can't animate nodes that are leaving the DOM, as their
nodes are instantly destroyed.
To solve the first issue I've adopted Angular's convention. It's
implemented in ReactTransitionableChild.
The second part is what's tricky. To do this I've implemented three modules:
- ReactTransitionableChild, which can keep its old children around if they
change to null
- ReactTransitionKeySet, which can look at a prev and next set of child
keys and merge them in a reasonable way
- ReactTransitionGroup, which combines ReactTransitionableChild and
ReactTransitionKeySet to keep nodes that are leaving the DOM in the
DOM until their animations are complete
Summary:
- Weren't pooling the Transaction in the batching strategy
- Creating a new closure for every event tick due to batchedUpdates()
- EnterLeaveEventPlugin creates a new array on each event.
I wonder if there is more optimization opportunity in accumulate(). Squinting at the fps graph this seems to be faster and waste less memory but it's hard to conclusively tell. I did verify that these were all hotspots though.
I've hit this a few times where I want to get to docs so I take whatever
my urlbar gives me and strip out the actual page so I can get to the
root, however that's a 404.
This introduces a super easy way to redirect, which could be handy in
the future as docs get rewritten.
I would much rather do this with a real htaccess file or even just
handle 404s gracefully, but that's not currently an option with GitHub
pages (since we generate our own and don't use a custom domain).
We need access to the instance cache for debugging tools. Ideally we want to
expose a more stable and supported interface but this seems like a quick win,
for now.
Sometimes you may need to detect if a value is a valid React class constructor. This enables that and prevents future consumers from getting caught in the trap of depending on an internal implementation detail we might change.
Currently this works for classes created with `React.createClass` as well as `React.DOM.*`.
This adds a `ReactDOMButton` module that shims the native `<button>` React component so it doesn't receive mouseup, mousemove, mousedown, click, or double-click events when its disabled property is truthy.
Today mixins can't easily be stateful because they can't provide getInitialState(). This allows multiple getInitialState() methods as long as they don't return objects that have conflicting keys. In that case, we throw.
`content`, `httpEquiv`, `charSet` are all needed. We're currently
working around this in `react-page`.
`content` is the risky one here since we previously supporting using
`content` to set the text content. We removed support for that in
e998041229 so the risk is minimal, there
just might be some lingering old code.
Fixes#292
Test Plan: Visit `data:text/html,<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" charset="utf-8"></head>`
```
var m = document.querySelector('meta');
m.httpEquiv; // Content-Type
m.httpEquiv = 'foo';
m.httpEquiv; // foo
m.charset; // undefined
m.charSet; // undefined
m.getAttribute('charset'); // utf-8
m.setAttribute('charset', 'bar');
m.getAttribute('charset'); // bar
m.content; // text/html; charset=utf-8
m.content = 'baz';
m.content; // baz
```
- Add pagination
- Display full content in /blog
- Truncate Recent posts
- Add permalink that lists all the blog posts
- Add spacing and bullet around recent posts to make it more readable
There are certain cases where you can end up with a collision with an implicit
key (array index) if your explicit key prop is a number. They should use
different namespaces. Therefore I wrap explicit keys in curlies and implicit
array indices in brackets.
I added a simple test case, but another case came up on the mailing list. Where
undefined entries in an array actually results in an entry and therefore an
implicit key.
Summary: Allows rendering of React into the "document" as opposed to into a
particular node. To recap some basics:
document: One level above the <html> tag - like the browser.
document.documentElement: <body>
To support full-page server side rendering, we need to be able to render
*everything* including the HTML/BODY tags. This allows that.
Closes#250.
Test Plan:
With multiple and not, verified: With defaultValue, the correct option is picked initially, user changes change the selection, and changes to defaultValue have no effect. With value, the correct option is picked initially, user changes do nothing, and changes to value change the selection.
Also ran the tests.
Many of React's util functions are non-redundant with Facebook's core
libraries, so move them out of React into a central location (out of
this repo).
These files were not getting used by any part of React core, so didn't
actually belong here anyway.
Instead of changing `traverseAllChildren`, keep that around for perf
reasons (for the hot code path `flattenChildren`)
Introduce `ReactChildren.map` and `ReactChildren.forEach`
which mirrors `Array.prototype.map` and `Array.prototype.forEach`. This
involves a rename of `mapAllChildren`
This fixes a reconciliation bug introduced by adffa9b0f4.
The new unit test case exhibits the bug. When a component that has rendered child components is updated to render inline text, we usually:
# Unmount and remove all child components.
# Set the new inline text content.
However, with batched child operations, we do not **remove all child components** until later. The current implementation will set the inline text content and blow away those nodes, causing a fatal when `ReactMultiChild` later tries to find and remove those nodes.
This fixes the bug by ensuring that text content changes are also enqueued.
The original tests were flawed because the `Danger` module exploits the fact that all React-generated markup has at least one attribute. This allows the module to extract node names from markup strings faster.
However, the tests were passing in strings of markup with no attributes.
Also, this fixes a test failure due to the test trying to set text content into a `<tr>` which is typically disallowed by browsers (and PhantomJS). This changes it to use `<td>` instead.
Not all testing environments will support setting the `innerHTML` descriptor. For example, PhantomJS initializes the `innerHTML` property as not configurable.
Setting `innerHTML` is slow: http://jsperf.com/react-child-creation/2
This reduces the number of times we set `innerHTML` by batching markup generation in a component tree.
As usual, I cleaned up the `ReactMultiChild` module significantly.
== Children Reconciliation ==
When a `ReactNativeComponent` reconciles, it compares currently rendered children, `prevChildren`, with the new children, `nextChildren`. It figures out the shortest series of updates required to render `nextChildren` where each update is one of:
- Create nodes for a new child and insert it at an index.
- Update an existing node and, if necessary, move it to an index.
- Remove an existing node.
This serializable series of updates is sent to `ReactDOMIDOperations` where the actions are actually acted on.
== Problem ==
There are two problems:
# When a `ReactNativeComponent` renders new children, it sets `innerHTML` once for each contiguous set of children.
# Each `ReactNativeComponent` renders its children in isolation, so two components that both render new children will do so separately.
For example, consider the following update:
React.renderComponent(<div><p><span /></p><p><span /></p></div>, ...);
React.renderComponent(<div><p><img /><span /><img /></p><p><img /><span /><img /></p></div>, ...);
This will trigger setting `innerHTML` four times.
== Solution ==
Instead of enqueuing the series of updates per component, this diff changes `ReactMultiChild` to enqueue updates per component tree (which works by counting recursive calls to `updateChildren`). Once all updates in the tree are accounted for, we render all markup using a single `innerHTML` set.
There is a circular dependency between `ReactID`, `ReactMount` and
`ReactInstanceHandles`. Ben and I talked about this today. It seems like the
simplest solution is to consolidate a lot of the code that Ben recently wrote
into `ReactMount`. We can later find ways to trim code out of this module
without causing circular deps.
As @leebyron and balpert pointed out, if the markup on the server is differnet than what the client expects undefined behavior and chaos may ensue. A good fallback
is for us to just inject the client-side markup (as it is the source of truth) and warn the user in __DEV__ that something is wrong. In order to do a fast
browser-independent check of the DOM I use an adler32 checksum of the generated markup. I believe this is better than a simple innerHTML compare because different
browsers massage innerHTML differently.
This works around a bug with listening to clicks using event delegation on Mobile Safari using an event plugin.
NOTE: We don't enable touch events by default, so I don't know if would want to inject this plugin by default. In fact, I'm not sure what our strategy is at all for when to invoke `React.useTouchEvents(true)`.
We already skip `null` and `undefined` when building up the stringified html on first render, but if you update a component to the *exact same* conditions, React will leave the DOM in a different state. We shouldn't do that.
This was not necessary when we were running each test in its own
`<iframe>`, and it doesn't seem to affect any test behavior currently, but
it seems wise for the sake of test isolation and hygiene.
We don't sync upstream polyfills (because we don't have a story for how
they would be used), so this needs to be updated manually.
Sacrificed some negligible performance optimizations to reduce the number
of different cases from four to one.
It's important to test this implementation in PhantomJS, since that's the
only browser that I know of where built-in functions sometimes do not have
a `.prototype`.
This cuts the running time of `grunt phantom:run` from 4.4s to 3.1s on my
machine, because we no longer have to load/execute a separate instance of
`react-test.js` in a separate `<iframe>` for each test.
getConfig needs to be a function because grunt.config.data.pkg.version isn't available at the time that grunt/config/jsx/jsx.js is required.
Test Plan:
grunt build, grunt lint, grunt test all work. After building, both react.js and react.min.js contain the version number.
Here are some ideas that I think work better:
- 15 repetitions of "React". Removed a few.
- The "two main ideas" weren't clearly separated. I put them under different headers and simplified the wording.
- The "Give it Five Minutes section didn't sound as reassuring. Made it sound more certain.
This is still the same amount of duplication, except way easier to
parse. Docs nav now lives in `_config.yml` and you must restart jekyll
to see changes to that list (since config is only read at jekyll launch)
This will let us keep docs in order on the filesystem but have
reasonable permalinks. If we add something at 02- it doesn't result in
lots of broken links.
A silent upgrade from graceful-fs v1.2.2 to v1.2.3 (a dependency for both
Commoner and Populist) broke the build process, even though tests were
still passing. The 2.0.0 version fixes whatever was broken, though I won't
pretend to know exactly what the root cause was.
We're using populist for building the bundle of test modules and their
dependencies, so it seems worthwhile for consistency to do the same for
the test harness.
It's not always possible to update `rootElementsByReactRootID` when the
contents of the container are re-rendered; for instance, when we call
`dangerouslyReplaceNodeWithMarkup` or `dangerouslySetInnerHTML`. Since
this bookkeeping is just trying to warn about potentially problematic
manipulations of the root element, and we can be relatively sure that a
new element with the same ID is logically the same element, this diff
avoids warning in such cases.
This fixes known browser bugs with rendering markup using `innerHTML` in IE ([[http://support.microsoft.com/kb/276228 | here is an example of one]]).
This is a subset of what `HTML` (and jQuery) does, and we should eventually consider pulling it out into a separate module to reduce code duplication. For now, this is the minimal set of changes needed to unbreak React in production.
We can afford to use a subset of what `HTML` does because we have the luxury of knowing that the markup is generated sanely with proper closing tags, etc.
This implements a `<select>` component that supports `value` and `defaultValue`. It also changes `<option>` to warn when the `selected` prop is supplied.
Use the new `traverseChildren` utility to perform `mapChildren`.
The goal is to get as close to the bavior of the semantics of
`Array.prototype.map`, but also in a way that understands deeply nested arrays
and objects.
Biggest win here is that we'll strip out the console.error from
EventListener and we won't need to suggest people use a console
polyfill with the minified build.
No longer injecting __MOCK__ as a global constant (it's just a config
property now).
Turns out the `grunt jsx:debug` task was never necessary for tests.
When require("mock-modules").dumpCache() is called, all mock functions
previously created continue to refer to the old dirtyMocks array.
If we replace that array with a new one, those mock functions will never
have their .mockClear() methods called again.
The upstream version of mocks.js pulls a similar global trick, and I never
understood why until now.
We don't currently attempt to mock modules automatically, but we do
respect require("mock-modules").mock, .dontMock, and .dumpCache.
I'm going to keep investigating auto-mocking, since that would move us
much closer to the behavior used within Facebook.
Closes#154.
Closes#155.
This reverts commit dd1d49b360.
The license is actually supposed to look like that. That section is
boilerplate for others to apply the license to their own work. See
immediately above...
> To apply the Apache License to your work, attach the following
> boilerplate notice, with the fields enclosed by brackets "[]"
> replaced with your own identifying information. (Don't include
> the brackets!)
This fixes two bugs related to string-casting in React:
# Setting `<input value={0} />` would use an empty `value` because `0` is falsey.
# Using `onChange` and `setState` with non-strings could lead to an infinite loop.
The latter is possible with controlled inputs when:
- User changes input value.
- `onpropertychange` fires.
- `ChangeEventPlugin` dispatches `onChange`.
- A handler responds via `this.setState` with a non-string value (e.g. a number).
- The input re-renders and re-sets `value`.
- The new `value` is not a string, but the current `value` (read from the element) is cast to a string automatically by the browser.
- This triggers another `onpropertychange`.
- `ChangeEventPlugin` dispatches another `onChange`.
- ...
This is a bit unfortunate, but it'll shut lint up for the time being. We
can't just change the modules to use `module.exports = { ... }` due to
how we handle circular dependencies internally (`ReactMount` require
`ReactID` and vice versa).
When each component unmounts, it already cleans up its respective entry in the node cache. Let's stop blowing away the entire node cache unnecessarily.
This should improve performance because a React component's root will never need to be searched for more than once.
This is a micro-optimization that reduces the lookup time for missing lifecycle methods. The extra amount of memory is linear to the number of components that exist on a page which I think is a worthwile trade-off.
When `ReactNativeComponent` updates, it calls `updatePropertyByID` in `ReactDOMIDOperations` which calls `DOMPropertyOperations`. However, in `ReactDOMIDOperations`, we will lookup the node for an ID using `ReactID.getNode`. This wastes time looking for nodes when we may not need to ever update it (e.g. `children`).
This changes `ReactNativeComponent` to bail out sooner.
This adds two new warnings and one new invariant:
- Warn when using React.autoBind() that it is deprecated.
- Throw when calling bind() on an autobound method with the wrong value of "this". Today we'll silently ignore the provided value, which is confusing.
- Warn when calling bind() on an autobound method with the *right* value of "this" and no other arguments. This is already done for you by React.
There are other changes I'm sure but the most important is that module
sorting results in deterministic builds.
The biggest win here comes for releases. Previously we had to jump
through hoops to make sure the files we put in bower were the same files
we put on the CDN, were the same files packaged in the Ruby gem, were
the same files we packaged into a zip file, were the same file we used
when create PRs to CDNJS. Rebuilding docs also resulted in conflicting
versions so we had to be careful when committing. This takes away all of
that pain. We can build from the same revision and get the same files.
We're missing a bunch of elements. So I scraped them from https://developer.mozilla.org/en-US/docs/Web/HTML/Element. Here's the script I used (run from Firefox scratchpad):
```
Array.prototype.slice.call(document.querySelectorAll('div.index.widgeted li'))
.filter(function(li) {
return !/deprecatedElement|obsoleteElement|nonStdElement/.test(li.firstChild.className)
})
.map(function(li) {
// <tag> -> tag
return li.querySelector('code').textContent.replace(/<(.+)>/,'$1');
})
.join(': false,\n ');
```
I had to filter a couple more out (because there's some malformed content), but then it was simply merge with what we had and check to see if the new ones needed to omit the close tag.
This fixes our perf test by coping with edge cases like the
injection of `<tbody>` between `<table>` and `<tr>` nodes, which occurs
automatically in some browsers when we set `.innerHTML`.
Introducing more search branches would be risky if not for my previous
commit that made `findComponentRoot` breadth-first instead of depth-first.
This function needs to be as fast as possible for those cases when
`ReactID.getNode` can't rely on the `nodeCache`.
Breadth-first search prevents us from diving too deeply down the wrong
branches when the sought-after node can be found at a shallower level.
The queue required for breadth-first search is implemented by a single
array indexed by `childIndex`. To save space, only the `.firstChild` nodes
are stored, and we use `.nextSibling` to iterate over the other siblings
in a `while` loop.
When we render a new component into a container, we now record a reference to the rendered DOM node as `rootElementsByReactRootID[reactRootID]`, so that we can determine the actual container later on, in case `containersByReactRootID[reactRootID]` is no longer the true container.
If any component throws during reconciliation any subsequent reconciliation will break badly because ReactUpdates will be in an inconsistent state.
Add a finally block to prevent this.
Whenever a component is unmounted, we delete all listeners that might have been attached. This sucks because most applications, Facebook included, do not use every listener. There's a lot of wasted computation, especially if many components are mounted and unmounted.
This changes `deleteAllListeners` to more delete listeners more efficiently.
This fixes a bug with `ChangeEventPlugin` in IE8 and IE9. The extend of this bug includes:
- On IE8, not firing `onChange` immediately after `value` of an input is changed.
- On IE9, not firing `onChange` when backspacing.
Introduces a counterpart to mapChildren. It excludes empty children just as
mapChildren for compatibility. With might introduce something like
sliceChildrenIncludingEmptyValues at some point.
This behavior is new in Commoner v0.8.3, following the incorporation of
@jeffreylin's `DirWatcher` implementation:
https://github.com/jeffreylin/jsx_transformer_fun/blob/master/dirWatcher.js
Watching directories instead of files reduces the total number of open
files, and copes better with editors that save files by deleting and then
immediately recreating them.
Closes#60.
Closes#71.
If you are using bin/jsx independently, you may need to pass
--follow-requires to it if you rely on its dependency scanning.
Dependency scanning is still a good idea, but it's difficult to make it
work perfectly for everyone the first time they try bin/jsx.
Closes#131.
I still think the semantics of flattening children is valid but we'll
want to revert the flattening implementation while we solidify the
semantics and try another approach.
This reverts flattening so that this.props.children can once again be
either a single child, flat array or nested array.
mapChildren calls flattenChildren before doing anything else. This is
not the most efficient approach but I wanted to keep this inital diff
simple. It also ignores empty values for backwards compatibility.
We may want to try another approach where empty values are included
in the map.
Validation of keys is still done inside ReactComponent. Ideally I'd
like to extract that into a separate module but to avoid cyclic
dependencies, I'm keeping it in ReactComponent for now.
This fixes a race condition if the `onClick` tries to update the input or textarea (e.g. by calling `setState`):
<input
onClick={function(event) {
this.setState({somethingElse: true}); // Triggers an update.
// event.target.value is now equal to the old value, fail...
this.props.onChange(event);
})
/>
A dynamic value can be provided as a key to a child. Either as part of an object
or key property. This becomes part of the component's ID.
We have to be careful to escape this key before inserting it into the DOM since
it could become a vulnerability. We fixed this by escaping just the keys.
However, the current implementation breaks when you used escaped keys. The
internal value is escaped and the value used by getAttributeNode and
getElementById are both unescaped.
This fixes that by keeping the unescaped value internally but escaping it right
before the HTML is generated (like any other attribute).
This is important since business logic IDs (that should be used as keys)
contains characters that need to be escaped.
This changes `ReactDOMTextarea` to accept `defaultValue` and `value`. It will warn people about using children (but allow it and treat it as `defaultValue`, which is the current behavior).
Instead of simply logging the React ID of the `ancestorNode` when `findComponentRoot` fails, use a `try ... finally` to `console.error` the `ancestorNode`. This allows modern web inspectors to actually log a reference to the node (which may not have a React ID).
This means when people run into the problem, they will not have to execute:
require('ReactID').getNode(<copy+paste>);
NOTE: Admittedly, this will not log anything in IE8. That's fine, since IE8 has shitty console logging anyway.
Just a bit of byte savings for server rendering. Props to @benjamn for the base36 idea (and for making this diff easy).
With a little work we could probably get rid of the .r as well.
This changes React to throw when `ReactID.getNode()` fails to find a node. This method is used by two call sites:
- Implements `ReactComponent#getDOMNode`. This method already throws if a component is not mounted, and //all mounted components should be able to find their rendered root nodes//.
- Used by `ReactDOMIDOperations`. These call sites aleady assume that `getNode` returns a non-null. Currently, if the node is not found, this is the site that fatals (and the stack trace is much harder to debug).
The error message should make it //a lot// easier to debug unexpected DOM trees. In particular, this will help track down all the places where the browser inserts `<tbody>` unexpectedly.
This fixes a bug with components constructed with no owners, for example:
// Both the <div> and <span> have no owners.
React.renderComponent(<div><span /></div>, node);
They should have a composition level of 1 and their keys should be prefixed with 0 to indicate they were created without owners. However, they currently incorrectly get a composition level of 0 (which means that //their// children will have keys prefixed with 0, which is wrong).
The current `ReactInstanceHandles` has a bug where `findComponentRoot` barfs if it comes across a node that was not identified by React (via `ReactID`). This fixes that.
This was always a bug, but it became more apparent once we switched to `data-reactid` because arbitrary `document.createElement`'d nodes are much more likely to have an `id` than they are to have a `data-reactid`.
This final change is what we've all been waiting for.
Note that it no longer makes sense to use `document.getElementById` in
`getNode`, because that only ever worked with "id" attributes.
This prevents PhantomJS tests from hanging in the open-source React repo.
Until the advent of `"use strict"`, passing `null` as the context object
to `.call` or `.apply` resulted in `this` taking on the value of the
global object inside the invoked function.
Technically the `"use strict"` directive is supposed to make it possible
that `this === null`, but strict mode is not respected by all browsers,
including (unfortunately) PhantomJS.
Since these `expect`-ations are just testing binding behavior, let's not
make them also test strict mode `this` handling.
The `getDefaultProps` return value should not be dependent on any external data (including `this.props` and `this.state`), so the return value should be consistent everytime we call it.
This caches the return value so we do not do work and allocate memory unnecessarily.
A node is considered valid if it
1. has the expected ID (more of a sanity check than something that is
ever likely to go wrong), and
2. is contained by a currently mounted container.
When these requirements are met, we can be confident that
`ReactMount.findReactRenderedDOMNodeSlow(node.id) === node`, which is
important for cache consistency because `findReactRenderedDOMNodeSlow` is
what we fall back to when we don't find a node in the cache.
Point 2 is a subtle requirement, because it allows nodes to be valid even
if they are not currently contained by a document. Rendering into a
detached node is okay, in other words (which is something that
`document.getElementById` never properly accounted for).
Containment testing takes linear time in the depth of the DOM, which
sounds unfortunate until you realize that virtually all browsers support a
native `ancestor.contains(descendant)` method, and in practice the vast
majority of nodes are either orphaned with `.parentNode === null` or not
very deep relative to their container.
Upgrade `TextChangeEventPlugin` to be the `onChange` event that React
fires. In React, `onChange` will now fire when `input` fires for form elements in
modern browsers.
Handle this for:
input[type=text]
input[type=password]
input[type=checkbox]
input[type=radio]
textarea
select
Support:
- OSX Chrome
- OSX Safari
- OSX Firefox
- Win 7 / IE8
- Win 7 / IE9
- Win 7 / IE10
Everything works but caret selection / placement differs from browser to
browser.
For <select> elements, the event is fired with `change`. This is a
conscious decision, even though in some browsers (OSX firefox, IE), it
can be argued that the event should fire more due to how the UI looks.
Builds on https://github.com/facebook/react/pull/75, which handled only
text inputs.
These modules have been superseded by `ReactID`. Since they were only used
internally, and I have updated all client code that previously assumed
their existence, I believe they can be dropped for good.
Although it would have been nice to prime the entire tree and achieve a
cache hit rate of 100%, that cost would have to be paid up front, during
page rendering.
This patch avoids priming up front in favor of making the most of the work
done by `ReactMount.findReactRenderedDOMNodeSlow`, which calls
`ReactID.getID` while traversing the rendered DOM. The insight is this: if
`getID` simply primes the cache whenever it finds a new ID, then
`findReactRenderedDOMNodeSlow` will end up priming quite a few more nodes
that are actually involved in `ReactID.getNode` lookups, and we won't need
`primeTree` at all.
`.grunt/` is the directory that is suggested for storing task related
files, and this file is not useful if it gets wiped out often. So I'm
moving the compare_size cache into `.grunt/` so we keep it around
longer.
This behavior seemed incorrect for composite components.
- isComponentMounted() represents ReactComponent's lifecycle of mounting
- isMounted() represents ReactCompositeComponent's lifecycle of isMounted()
Therefore, ReactComponents no longer have isMounted(). I think this is fine since it was not supposed to be public anyway.
Summary:
This is a proposal based loosely on the discussions I've had with @paulshen and @jwalke. It implements a shim for `React.DOM.input` (used as `<input>`) that supports two different use cases depending on whether `value` is provided or not.
If a `value` is //not// provided, the input will be initialized with the empty string (or `defaultValue`) and anytime the user changes the input, the `onChange` (or `onTextChange`) handler will be fired and the DOM will reflect the new changes.
React.renderComponent(
<input type="text" defaultValue="Untitled" onTextChange={handleChange} />,
container
);
If a `value` is provided, the input will be initialized to that value. Anytime the user changes the input, the `onChange` (or `onTextChange`) handler will be fired. However, the DOM will //not// reflect the new changes. If a `value` is provided, it is the responsibility of the owner to update the `value` prop passed in.
var value = "Untitled";
var input = React.renderComponent(
<input type="text" value={value} onTextChange={handleChange} />,
container
);
function handleChange(event) {
// Do something cool like strip out non-numbers.
var value = event.target.value.replace(/\D/g, '');
input.setProps({value: value});
}
This is just a start and we should build similar components for `textarea` and `select`. Also, this does not inject the new components because the changes are not backward compatible. Once we change all `<input>` uses to use `ReactDOMInput`, then we can inject.
The original autobinding diff made some assumptions about how methods were called on components that had to be reverted. This diff
enforces those assumptions in a test
Per our discussion - this is the general approach we'd like to take for
the public facing API.
var MyComponent = React.createClass({
render: function() {
return <div onClick={this.myCallback} />;
},
myCallback: function() {
}
});
Also removed some unnecessary calls to `document.getElementById`, which
will eventually cease to work for React-specific IDs.
This clears the way for the deprecation of `ReactDOMNodeCache` and
`getDOMNodeID`.
When we move away from using the "id" attribute to identify
React-generated elements, we will need the cache (formerly
ReactDOMNodeCache) to be tied much more closely to the code that looks
elements up by ID (getDOMNodeID) and sets element IDs, since the magic of
document.getElementById will no longer be available.
The priming functions are going to come in handy when we create new DOM
fragments in mountComponent.
For backwards compatibility, the ReactDOMNodeCache and getDOMNodeID
modules still exist, but they are implemented entirely in terms of
functions exported from ReactID.
This adds a `toBeComponentOfType` method to `reactComponentExpect`. Now that we are injecting composite native components, `toBeDOMComponentWithTag` will not suffice and should be deprecated.
_updateDOMChildren was already updating textContent so we don't need to
do it in _updateDOMProperties. Additionally, don't update .value if
it'll be a noop because it has side-effects (like moving the cursor) in
some browsers (like IE 9).
Refactor tests to be a bit more robust and a bit cleaner too.
It turns out that (at least for local development) npm has a long
standing bug where it doesn't recognize changing dependencies stored as
git urls (see https://github.com/isaacs/npm/issues/1727). Luckily npm
understand tarballs and GitHub provides tarballs for every commit, so
the workaround is easy, though unfortunate.
We have less dynamic arrays in the code base now so let's start warning for all
the cases where we pass dynamic arrays without keys.
I use the displayName to point out which component's render method was
responsible. I only warn once per component. If the child was created in a
different component (and passed as a property) I also show the owner of the
child. Maybe it should've attached the key at a higher level.
This does give false positives for arrays that are truly static. Those should
probably be refactored to use the XML syntax if possible.
06cff60bc1 made it so that `this.props.children` was no longer set when
none were provided.
var x = <div />;
This caused an issue if the code was relying on the following not
transferring children.
return this.transferPropsTo(<div />);
// this now transfer children
This fixes the last known parts of the flattening experiment. This has grown to
be somewhat complex and potentially fragile because of it. We may end up
reverting flattening in the future or address it slightly differently.
The purpose of this diff is to test if we've finally understood the real world
edge cases that flattening can lead to and how we have to key components to
cover those cases.
With this commit we never rekey the internal _key property. The semantics is
that once a component passes through a composite component, it's identity is
frozen.
props.key should accept numeric values and booleans which includes 0 and false.
This fixes the truthiness check.
We should never warn about missing key properties if a component is passed as a
static child. The _key acts as a flag to determine whether this component
was checked already.
Dumping the mock cache isn't dirying the modules in the open source version, so we have to unit test a different way. If we can fix the unit test framework, we should revert this.
Also, I added strict mode to `EventPluginRegistry.js`.
See: https://github.com/facebook/react/pull/91
Small utility that extracts and validates that there is only a single
child passed to a React composite component. The benefit here is that we
abstract away *how* the children are actually stored while we iterate on
different approaches. This way we won't break callsites as we try different
ideas. When we settle on a final approach, all of these callsites will still
work.
There are currently two places where we lookup and cache nodes: `ReactDOMNodeCache` and `ReactComponent`. Instead, we should just consolidate caches and make `ReactComponent` use `ReactDOMNodeCache`.
This should prevent "Warning: stdout maxBuffer exceeded" errors.
Also piping child process stdout and stderr to the parent process, so
you can see more of what's happening during the build process.
The biggest improvement is that we'll now insert each parsed JSX script
back into a `<script>` tag with the body set. This allows the browser to
execute these scripts normally. Using `Function(functionBody)` or
`eval(functionBody)` both execute in window scope, but `var` assignments
don't actually get set on window (unlike everywhere else).
I also did some cleanup to make the code a little bit more readable.
In my minimal test cases this didn't break anything (scripts loaded in
the right order).
This commit adds an optional callback as a second argument to
`setState`, to be called after `setState` runs.
We never guarantee synchronous execution of `setState`, and as per
@phunt, we don't want to make that guarantee because we may eventually
batch calls to `setState`. @jwalke agrees with him.
If you defined a global named `id` (a horrible name, I know) then
getDOMNodeID(window) would return that object. Since only DOM nodes can
have IDs, this should be a noop change otherwise.
Test Plan:
Verified that document.documentElement and document.body both support
getAttributeNode properly in latest Chrome and in IE8.
Dumping the mock cache isn't dirying the modules, so we have to unit test a different way. If we can fix our unit test framework, we should revert this.
Also, I added strict mode to `EventPluginRegistry.js`.
Summary: This invariant is unnecessary because `ReactComponent.Mixin.receiveProps` already asserts that this component is mounted. (Being mounted guarantees you have a DOM ID, look at `ReactComponent` and see when `this._rootNodeID` is mutated.)
This can be replicated with a custom component that always returns false`
from `shouldComponentUpdate`. A generic implementation might look like:
```
var StaticContainer = React.createClass({
shouldComponentUpdate: function() {
return false;
},
render: function() {
return this.transferPropsTo(this.props.children[0]);
}
});
```
And then used in JSX as
`<StaticContainer><div>Hello!</div></StaticContainer>`, resulting in
only `<div>Hello!</div>` being inserted into the DOM.
This fixes an edge case that can cause unnecessary mutations in the DOM. Namely, if a prop is falsey, it will get touched on every update by reconciliation. See unit test.
This cleans up the reconcilation path when adding a `style` prop (going from a falsey or no `style` to having one) by reducing the need for an object allocation and for-loop.
The `EventPluginHub` module was getting huge and scary. This pulls out all of the logic required to inject plugins and publish their event registration names into a new `EventPluginRegistry` module.
Functionally, nothing should have changed. I added many error checks to cover edge cases that we were not yet running into, but they are all in `EventPluginRegistry` and unit tested.
There is currently no way for components to know whether or not they are mounted. This means there's no way for callbacks to figure out if they can make certain assumptions (e.g. can `getDOMNode()` or `setState()` be safely invoked).
This adds an `isMounted` protected method that lets components properly handle callback behavior when unmounted.
Turns out my tests before weren't particularly useful because
receiveProps doesn't end up running componentDidUpdate since the
transaction never finishes. Now they use replaceProps instead (and I
verified that commenting out the "rootNode.value = ..." line makes the
tests fail, which wasn't true before).
The most obvious manifestation of this bug is visible here:
http://jsfiddle.net/spicyj/zzGas/. In short, when props are removed from a
component, the underlying HTML element doesn't have the attribute
removed.
This change should fix it, but unfortunately it (presumably) makes
_updateDOMProperties a bit slower.
The Commoner upgrade is a big one because it makes bin/jsx no longer
rewrite module identifiers to be relative by default, which should
reduce confusion for people trying to use it as a standalone
transformer.
Closes#80.
IE<9 relied on the `target` property being overriden. This adds back a hack that only applies in IE<9. I'll be able to revert this hack once I check in synthetic events.
This is just a simple rename of the event classes to `SyntheticEvent`. I've also updated the constructor arguments to be more correct:
- `dispatchConfig`: Data used by the plugin system for dispatching the event, for example: `{registrationName: 'onClick'}`
- `dispatchMarker`: An identifying marker used to describe where the event is occuring, for example: `.reactRoot[0]`
This is both a functional fix and performance fix for `ReactInstanceHandles`.
- `getFirstReactDOM` uses `indexOf` but should be checking ancestry (via `isMarker()`).
- Added `isAncestorIDOf`, checking ancestry can be way faster than getting a common ancestor: http://jsperf.com/react-ancestor-id-check
Change `ReactInstanceHandles` so that `getFirstCommonAncestorID` and `nextDescendantID` are now private (and documented to be only exposed for unit testing). Also:
- Renamed `nextDescendantID` to `getNextDescendantID`.
- Renamed `parentID` to `getParentID`.
I also organized `ReactInstanceHandles-test` by method names.
Functionally, this diff should not change anything.
IE8 doesn't support oninput and IE9 supports it badly but we can do
almost a perfect shim by listening to a handful of different events
(focus, blur, propertychange, selectionchange, keyup, keydown).
This always triggers event handlers during the browser's event loop (not
later in a setTimeout) and after the value property has been updated.
The only case I know of where this doesn't fire the event immediately is
if (in IE8) you modify the input value using JS and then the user does a
key repeat, in which case we fire the event on the second keydown.
Test Plan:
Modify ballmer-peak example to add es5-shim and to use onTextChange
instead of onInput. In IE8, IE9, and latest Chrome, make sure that the
event is fired upon:
* typing normally,
* backspacing,
* forward-deleting,
* cutting,
* pasting,
* context-menu deleting,
* dragging text to reorder characters.
After modifying the example to change .value, make sure that the event
is not fired as a result of the changes from JS (even when the input box
is focused).
Remove ReactMount.createComponentRenderer because it does not function
correctly.
var f = React.createComponentRenderer(<div />);
var container1 = document.createElement('div');
var container2 = document.createElement('div');
f(container1);
f(container2); // error because mounting same instance into new root
React's top-level event delegation dispatches `AbstractEvent` objects that contain:
- `nativeEvent`, the original browser event.
- `data`, an object with custom normalized properties.
This diff creates a set of `DelegateEvent` classes that will replace `AbstractEvent`. The goal is two-fold:
# Provide a cross-browser implementation that conforms to the DOM Level 3 Events API so people don't have to use `nativeEvent`.
# Generalize the event object API so that it can be shared by `DOMEventManager`, a top-level event delegation WIP.
This simply implements the classes. I will follow-up by replacing `AbstractEvent` with them.
Type coersion bug and ID breaking assumption.
Names need to be wrapped in something unique since otherwise two unique siblings
can end up having IDs that are subsets of eachother.
There are to reasons to prefer a `persist` method on the event rather than a static method:
- In open source, people do not have access to `AbstractEvent`.
- This will allow people to persist events without requiring another module.
- This will make refactors easier and more flexible.
As of Commoner v0.6.11, the default is to put the cache files in
output/.module-cache, which used to be build/modules/.module-cache
before this commit. That still happens when you run bin/jsx directly,
just not for grunt tasks anymore.
The module cache needs to be cleared much less often than
build/modules, so it doesn't make sense to throw away all that work.
This improved browser support for the `wheel` event.
- Try to use `wheel` event (DOM Level 3 Specification).
- Fallback to `mousewheel` event.
- Fallback to `DOMMouseWheel` (older Firefox).
Also, since `wheel` is the standard event name, let's use that in React.
NOTE: The tricky part was detecting if `wheel` is supported for IE9+ because `onwheel` does not exist.
Test Plan:
Execute the following in the console on a page with React:
var React = require('React');
React.renderComponent(React.DOM.div({
style: {
width: 10000,
height: 10000
},
onWheel: function() {
console.log('wheel');
}
}, null), document.body);
Verified that mousewheel events are logged to the console.
Verified in IE8-10, Firefox, Chrome, and Safari.
Summary:
This makes a few changes to React Core, most notably `ReactEventEmitter` and `ReactEventTopLevelCallback`.
- Changed `ReactEventEmitter` to use `EventListener` (instead of `NormalizedEventListener`).
- Deleted `NormalizedEventListener` (which was previously broken).
- Created `getEventTarget` which is used to get a normalized `target` from a native event.
- Changed `ReactEventTopLevelCallback` to use `getEventTarget`.
- Renamed `abstractEventType` to `reactEventType` in `AbstractEvent`.
- Reanmed `abstractTargetID` to `reactTargetID` in `AbstractEvent`.
- Removed `originatingTopLevelEventType` from `AbstractEvent` (unused and violates encapsulation).
- Removed `nativeEvent.target === window` check when refreshing authoritative scroll values (unnecessary).
This actually fixes React because `NormalizedEventListener` does not currently do what it promises to do (which is normalizing `target` on the native event). The `target` event is read-only on native events.
This also revises documentation and adds `@typechecks` to a few modules.
NOTE: Most importantly, this sets the stage for replacing `AbstractEvent` with `ReactEvent` and subclasses, piecemeal.
Summary: Since grepping for `update` and `updateAll` is pretty hard, I had these these functions call through but complain loudly. This noisy call through has been in prod for over a week and I haven't heard any complains, so let's take it out altogether.
ReactEvent should be reserved for the actual object created when an
event fires. The current ReactEvent is more like EventEmitter than
anything (e.g. it sets up delegation, provides methods to attach and
remove listeners).
We need to make sure that deleteAllListeners() is invoked before we call
the superclass's unmountComponent() method or else we will lose
this._rootNodeID.
I also added an invariant and unit test to make sure we do not break
this in the future.
If a React component's render() fatals, it may contaminate
ReactCurrentOwner. This will cause the owner to be set improperly for
the next React.renderComponent() invocation (which causes an owner to be
set when there shouldn't be one).
As it turns out, default values are very useful. This implements
getDefaultProps(), a hook for components to provide prop values when
a prop is not specified by the user.
var container = ...; // some DOM node
React.renderComponent(<div />, container);
React.renderComponent(<span />, container);
This should replace the rendered <div> with a <span>, effectively
reconciling at the root level.
Currently we're mutating _key. Mutation here is fine, but it needs to
be idempotent - which it's not. This is causing some issues.
Instead I reassign the _key every time it passes through a flattening.
This means that it's unique and stable for a single pass through a composite
component. When it's repassed another level, it loses it previous
identity and is rekeyed by it's new location.
For auto-generated keys by index, this actually means it has the same
semantics as before flattening.
For explicit keys, it has the effect that keys need to be unique at
every level. Regardless of how the key got there. Every component needs to ensure
that it doesn't combine keys from two different sources that may collide. This
is also inline with the old semantics but less intuitive in the new model.
flattenChildren was only using key when child.mountInContainerNode
exists, which is defined on ReactCompositeComponent, and not
ReactNativeComponent.
This uses the isValidComponent() fn to see if we should use this key.
Some improvements to how style={{x:y}} is handled in React:
* ignores null styles, rather than setting them.
Codez:
var highlighted = false;
<div style={{color: highlighted ? 'red' : null}} />
Before:
<div style="color:;"></div>
After:
<div></div>
Respects that 0 has no units.
This expects static children as additional arguments to the constructor
and flattens any array arguments one level deep.
Component(props, child1, child2, arrayOfChildren, child3) ->
.props.children = [child1, child2, ...arrayOfChildren, child3]
This can avoid an additional heap allocation for the unflat array.
It allows you to pass nested arrays and objects like you used to. Those
aren't immediately flattened. That makes this a fairly safe change.
Passing a dynamic array without key properties will yield a warning
(once). Might consider throwing later.
Once we change the transpiler to use the new syntax, you'll end up with
a single flat array in normal usage.
This doesn't actually update the JSX transform.
When there isn't any React node in the DOM, unmountAndReleaseReactRootNode
threw an exception because component was undefined. Instead, return whether we
were able to unmount the component.
Test Plan:
With the ballmer-peak example (modified to use input), tested that the
percentage updates when adding or deleting text in the field on Chrome
and IE9. After adding es5-shim and es5-sham to the ballmer-peak page,
IE8 works properly too.
onInput has the advantage that it responds to repeated key events before
onKeyUp and is called when modifying the input without the keyboard
(such as pasting with the mouse).
Test Plan:
Opened the ballmer-peak example and docs homepage in Chrome and checked
that both examples update whenever the text is changed.
'input' is supported in IE9+ and all other browsers according to
https://developer.mozilla.org/en-US/docs/Web/API/window.oninput
Test Plan:
Modified ballmer-peak example to use onInput instead of onKeyUp and
tested that it works properly on latest Chrome.
2013-05-30 18:20:34 -07:00
593 changed files with 43042 additions and 15794 deletions
- The lifecycle methods `componentDidMount` and `componentDidUpdate` no longer receive the root node as a parameter; use `this.getDOMNode()` instead
- Whenever a prop is equal to `undefined`, the default value returned by `getDefaultProps` will now be used instead
-`React.unmountAndReleaseReactRootNode` was previously deprecated and has now been removed
-`React.renderComponentToString` is now synchronous and returns the generated HTML string
- Full-page rendering (that is, rendering the `<html>` tag using React) is now supported only when starting with server-rendered markup
- On mouse wheel events, `deltaY` is no longer negated
- When prop types validation fails, a warning is logged instead of an error thrown (with the production build of React, type checks are now skipped for performance)
- On `input`, `select`, and `textarea` elements, `.getValue()` is no longer supported; use `.getDOMNode().value` instead
-`this.context` on components is now reserved for internal use by React
#### New Features
- React now never rethrows errors, so stack traces are more accurate and Chrome's purple break-on-error stop sign now works properly
- Added support for SVG tags `defs`, `linearGradient`, `polygon`, `radialGradient`, `stop`
- Added support for more attributes:
-`crossOrigin` for CORS requests
-`download` and `hrefLang` for `<a>` tags
-`mediaGroup` and `muted` for `<audio>` and `<video>` tags
-`noValidate` and `formNoValidate` for forms
-`property` for Open Graph `<meta>` tags
-`sandbox`, `seamless`, and `srcDoc` for `<iframe>` tags
-`scope` for screen readers
-`span` for `<colgroup>` tags
- Added support for defining `propTypes` in mixins
- Added `any`, `arrayOf`, `component`, `oneOfType`, `renderable`, `shape` to `React.PropTypes`
- Added support for `statics` on component spec for static component methods
- On all events, `.currentTarget` is now properly set
- On keyboard events, `.key` is now polyfilled in all browsers for special (non-printable) keys
- On clipboard events, `.clipboardData` is now polyfilled in IE
- On drag events, `.dragTransfer` is now present
- Added support for `onMouseOver` and `onMouseOut` in addition to the existing `onMouseEnter` and `onMouseLeave` events
- Added support for `onLoad` and `onError` on `<img>` elements
- Added support for `onReset` on `<form>` elements
- The `autoFocus` attribute is now polyfilled consistently on `input`, `select`, and `textarea`
#### Bug Fixes
- React no longer adds an `__owner__` property to each component's `props` object; passed-in props are now never mutated
- When nesting top-level components (e.g., calling `React.renderComponent` within `componentDidMount`), events now properly bubble to the parent component
- Fixed a case where nesting top-level components would throw an error when updating
- Passing an invalid or misspelled propTypes type now throws an error
- On mouse enter/leave events, `.target`, `.relatedTarget`, and `.type` are now set properly
- On composition events, `.data` is now properly normalized in IE9 and IE10
- CSS property values no longer have `px` appended for the unitless properties `columnCount`, `flex`, `flexGrow`, `flexShrink`, `lineClamp`, `order`, `widows`
- Fixed a memory leak when unmounting children with a `componentWillUnmount` handler
- Fixed a memory leak when `renderComponentToString` would store event handlers
- Fixed an error that could be thrown when removing form elements during a click handler
- Boolean attributes such as `disabled` are rendered without a value (previously `disabled="true"`, now simply `disabled`)
-`key` values containing `.` are now supported
- Shortened `data-reactid` values for performance
- Components now always remount when the `key` property changes
- Event handlers are attached to `document` only when necessary, improving performance in some cases
- Events no longer use `.returnValue` in modern browsers, eliminating a warning in Chrome
-`scrollLeft` and `scrollTop` are no longer accessed on document.body, eliminating a warning in Chrome
- General performance fixes, memory optimizations, improvements to warnings and error messages
### React with Addons
-`React.addons.TestUtils` was added to help write unit tests
-`React.addons.TransitionGroup` was renamed to `React.addons.CSSTransitionGroup`
-`React.addons.TransitionGroup` was added as a more general animation wrapper
-`React.addons.cloneWithProps` was added for cloning components and modifying their props
- Bug fix for adding back nodes during an exit transition for CSSTransitionGroup
- Bug fix for changing `transitionLeave` in CSSTransitionGroup
- Performance optimizations for CSSTransitionGroup
- On checkbox `<input>` elements, `checkedLink` is now supported for two-way binding
### JSX Compiler and react-tools Package
- Whitespace normalization has changed; now space between two tags on the same line will be preserved, while newlines between two tags will be removed
- The `react-tools` npm package no longer includes the React core libraries; use the `react` package instead.
-`displayName` is now added in more cases, improving error messages and names in the React Dev Tools
- Fixed an issue where an invalid token error was thrown after a JSX closing tag
-`JSXTransformer` now uses source maps automatically in modern browsers
-`JSXTransformer` error messages now include the filename and problematic line contents when a file fails to parse
## 0.8.0 (December 19, 2013)
### React
* Added support for more attributes:
*`rows` & `cols` for `<textarea>`
*`defer` & `async` for `<script>`
*`loop` for `<audio>` & `<video>`
*`autoCorrect` for form fields (a non-standard attribute only supported by mobile WebKit)
* Improved error messages
* Fixed Selection events in IE11
* Added `onContextMenu` events
### React with Addons
* Fixed bugs with TransitionGroup when children were undefined
* Added support for `onTransition`
### react-tools
* Upgraded `jstransform` and `esprima-fb`
### JSXTransformer
* Added support for use in IE8
* Upgraded browserify, which reduced file size by ~65KB (16KB gzipped)
## 0.5.2, 0.4.2 (December 18, 2013)
### React
* Fixed a potential XSS vulnerability when using user content as a `key`: [CVE-2013-7035](https://groups.google.com/forum/#!topic/reactjs/OIqxlB2aGfU)
## 0.5.1 (October 29, 2013)
### React
* Fixed bug with `<input type="range">` and selection events.
* Fixed bug with selection and focus.
* Made it possible to unmount components from the document root.
* Fixed bug for `disabled` attribute handling on non-`<input>` elements.
### React with Addons
* Fixed bug with transition and animation event detection.
## 0.5.0 (October 16, 2013)
### React
* Memory usage improvements - reduced allocations in core which will help with GC pauses
* Performance improvements - in addition to speeding things up, we made some tweaks to stay out of slow path code in V8 and Nitro.
* Standardized prop -> DOM attribute process. This previously resulting in additional type checking and overhead as well as confusing cases for users. Now we will always convert your value to a string before inserting it into the DOM.
* Support for Selection events.
* Support for [Composition events](https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent).
* Support for additional DOM properties (`charSet`, `content`, `form`, `httpEquiv`, `rowSpan`, `autoCapitalize`).
* Support for additional SVG properties (`rx`, `ry`).
* Support for using `getInitialState` and `getDefaultProps` in mixins.
* Support mounting into iframes.
* Bug fixes for controlled form components.
* Bug fixes for SVG element creation.
* Added `React.version`.
* Added `React.isValidClass` - Used to determine if a value is a valid component constructor.
* Removed `React.autoBind` - This was deprecated in v0.4 and now properly removed.
* Renamed `React.unmountAndReleaseReactRootNode` to `React.unmountComponentAtNode`.
* Began laying down work for refined performance analysis.
* Better support for server-side rendering - [react-page](https://github.com/facebook/react-page) has helped improve the stability for server-side rendering.
* Made it possible to use React in environments enforcing a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Security/CSP/Introducing_Content_Security_Policy). This also makes it possible to use React to build Chrome extensions.
### React with Addons (New!)
* Introduced a separate build with several "addons" which we think can help improve the React experience. We plan to deprecate this in the long-term, instead shipping each as standalone pieces. [Read more in the docs](http://facebook.github.io/react/docs/addons.html).
### JSX
* No longer transform `class` to `className` as part of the transform! This is a breaking change - if you were using `class`, you *must* change this to `className` or your components will be visually broken.
* Added warnings to the in-browser transformer to make it clear it is not intended for production use.
* Improved compatibility for Windows
* Improved support for maintaining line numbers when transforming.
## 0.4.1 (July 26, 2013)
### React
*`setState` callbacks are now executed in the scope of your component.
*`click` events now work on Mobile Safari.
* Prevent a potential error in event handling if `Object.prototype` is extended.
* Don't set DOM attributes to the string `"undefined"` on update when previously defined.
* Improved support for `<iframe>` attributes.
* Added checksums to detect and correct cases where server-side rendering markup mismatches what React expects client-side.
### JSXTransformer
* Improved environment detection so it can be run in a non-browser environment.
## 0.4.0 (July 17, 2013)
### React
* Switch from using `id` attribute to `data-reactid` to track DOM nodes. This allows you to integrate with other JS and CSS libraries more easily.
* Support for more DOM elements and attributes (e.g., `<canvas>`)
* Improved server-side rendering APIs. `React.renderComponentToString(<component>, callback)` allows you to use React on the server and generate markup which can be sent down to the browser.
*`prop` improvements: validation and default values. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/11/react-v0-4-prop-validation-and-default-values.html)
* Support for the `key` prop, which allows for finer control over reconciliation. [Read the docs for details...](http://facebook.github.io/react/docs/multiple-components.html)
* Removed `React.autoBind`. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/02/react-v0-4-autobind-by-default.html)
* Improvements to forms. We've written wrappers around `<input>`, `<textarea>`, `<option>`, and `<select>` in order to standardize many inconsistencies in browser implementations. This includes support for `defaultValue`, and improved implementation of the `onChange` event, and circuit completion. [Read the docs for details...](http://facebook.github.io/react/docs/forms.html)
* We've implemented an improved synthetic event system that conforms to the W3C spec.
* Updates to your component are batched now, which may result in a significantly faster re-render of components. `this.setState` now takes an optional callback as it's second parameter. If you were using `onClick={this.setState.bind(this, state)}` previously, you'll want to make sure you add a third parameter so that the event is not treated as the callback.
### JSX
* Support for comment nodes `<div>{/* this is a comment and won't be rendered */}</div>`
* Children are now transformed directly into arguments instead of being wrapped in an array
E.g. `<div><Component1/><Component2/></div>` is transformed into `React.DOM.div(null, Component1(null), Component2(null))`.
Previously this would be transformed into `React.DOM.div(null, [Component1(null), Component2(null)])`.
If you were using React without JSX previously, your code should still work.
### react-tools
* Fixed a number of bugs when transforming directories
* No longer re-write `require()`s to be relative unless specified
## 0.3.3 (June 20, 2013)
### React
* Allow reusing the same DOM node to render different components. e.g. `React.renderComponent(<div/>, domNode); React.renderComponent(<span/>, domNode);` will work now.
### JSX
* Improved the in-browser transformer so that transformed scripts will execute in the expected scope. The allows components to be defined and used from separate files.
### react-tools
* Upgrade Commoner so `require` statements are no longer relativized when passing through the transformer. This was a feature needed when building React, but doesn't translate well for other consumers of `bin/jsx`.
* Upgraded our dependencies on Commoner and Recast so they use a different directory for their cache.
* Freeze our esprima dependency.
## 0.3.2 (May 31, 2013)
### JSX
* Improved compatability with other coding styles (specifically, multiple assignments with a single `var`).
### react-tools
* Switch from using the browserified build to shipping individual modules. This allows react-tools to be used with [browserify](https://github.com/substack/node-browserify).
## 0.3.1 (May 30, 2013)
### react-tools
* Fix bug in packaging resulting in broken module.
React is a JavaScript library for building user interfaces.
* **Declarative:** React uses a declarative paradigm that makes it easier to reason about your application.
* **Efficient:** React computes the minimal set of changes necessary to keep your DOM up-to-date.
* **Flexible:** React works with the libraries and frameworks that you already know.
* **Just the UI:** Lots of people use React as the V in MVC. Since React makes no assumptions about the rest of your technology stack, it's easy to try it out on a small feature in an existing project.
* **Virtual DOM:** React uses a *virtual DOM* diff implementation for ultra-high performance. It can also render on the server using Node.js — no heavy browser DOM required.
* **Data flow:** React implements one-way reactive data flow which reduces boilerplate and is easier to reason about than traditional data binding.
[Learn how to use React in your own project.](http://facebook.github.io/react/docs/getting-started.html)
## The `react` npm package has recently changed!
If you're looking for jeffbski's [React.js](https://github.com/jeffbski/autoflow) project, it's now in `npm` as `autoflow` rather than `react`.
## Examples
We have several examples [on the website](http://facebook.github.io/react). Here is the first one to get you started:
We have several examples [on the website](http://facebook.github.io/react/). Here is the first one to get you started:
```js
/** @jsx React.DOM */
varHelloMessage=React.createClass({
render:function(){
return<div>{'Hello '+this.props.name}</div>;
return<div>Hello{this.props.name}</div>;
}
});
@@ -28,20 +32,20 @@ React.renderComponent(
This example will render "Hello John" into a container on the page.
You'll notice that we used an XML-like syntax; [we call it JSX](http://facebook.github.io/react/docs/syntax.html). JSX is not required to use React, but it makes code more readable, and writing it feels like writing HTML. A simple transform is included with React that allows converting JSX into native JavaScript for browsers to digest.
You'll notice that we used an HTML-like syntax; [we call it JSX](http://facebook.github.io/react/docs/jsx-in-depth.html). JSX is not required to use React, but it makes code more readable, and writing it feels like writing HTML. A simple transform is included with React that allows converting JSX into native JavaScript for browsers to digest.
## Installation
The fastest way to get started is to serve JavaScript from the CDN:
The fastest way to get started is to serve JavaScript from the CDN (also available on [CDNJS](http://cdnjs.com/#react)):
We've also built a [starter kit](http://facebook.github.io/react/downloads/react-0.3.2.zip) which might be useful if this is your first time using React. It includes a webpage with an example of using React with live code.
We've also built a [starter kit](http://facebook.github.io/react/downloads/react-0.9.0.zip) which might be useful if this is your first time using React. It includes a webpage with an example of using React with live code.
If you'd like to use [bower](http://bower.io), it's as easy as:
@@ -51,7 +55,7 @@ bower install --save react
## Contribute
The main purpose of this repository is to continue to evolve React core, making it faster and easier to use. If you're interested in helping with that, then keep reading. If you're not interested in helping right now that's ok too :) Any feedback you have about using React would be greatly appreciated.
The main purpose of this repository is to continue to evolve React core, making it faster and easier to use. If you're interested in helping with that, then keep reading. If you're not interested in helping right now that's ok too. :) Any feedback you have about using React would be greatly appreciated.
### Building Your Copy of React
@@ -81,12 +85,12 @@ At this point, you should now have a `build/` directory populated with everythin
We use grunt to automate many tasks. Run `grunt -h` to see a mostly complete listing. The important ones to know:
"undefined"==typeofc.createDocumentFragment||"undefined"==typeofc.createElement}g=b}catch(d){g=j=!0}})();vare={elements:k.elements||"abbr article aside audio bdi canvas data datalist details figcaption figure footer header hgroup main mark meter nav output progress section summary time video",version:"3.6.2",shivCSS:!1!==k.shivCSS,supportsUnknownElements:g,shivMethods:!1!==k.shivMethods,type:"default",shivDocument:q,createElement:p,createDocumentFragment:function(a,b){a||(a=f);if(g)returna.createDocumentFragment();
React was open sourced two weeks ago and it's time for a little round-up of what has been going on.
## Khan Academy Question Editor
It looks like [Ben Alpert](http://benalpert.com/) is the first person outside of Facebook and Instagram to push React code to production. We are very grateful for his contributions in form of pull requests, bug reports and presence on IRC ([#reactjs on Freenode](irc://chat.freenode.net/reactjs)). Ben wrote about his experience using React:
> I just rewrote a 2000-line project in React and have now made a handful of pull requests to React. Everything about React I've seen so far seems really well thought-out and I'm proud to be the first non-FB/IG production user of React.
>
> The project that I rewrote in React (and am continuing to improve) is the Khan Academy question editor which content creators can use to enter questions and hints that will be presented to students:
> [Read the full post...](http://benalpert.com/2013/06/09/using-react-to-speed-up-khan-academy.html)
## Pimp my Backbone.View (by replacing it with React)
[Paul Seiffert](https://blog.mayflower.de/) wrote a blog post that explains how to integrate React into Backbone applications.
> React has some interesting concepts for JavaScript view objects that can be used to eliminate this one big problem I have with Backbone.js.
>
> As in most MVC implementations (although React is probably just a VC implementation), a view is one portion of the screen that is managed by a controlling object. This object is responsible for deciding when to re-render the view and how to react to user input. With React, these view-controllers objects are called components. A component knows how to render its view and how to handle to the user's interaction with it.
>
> The interesting thing is that React is figuring out by itself when to re-render a view and how to do this in the most efficient way.
>
> [Read the full post...](https://blog.mayflower.de/3937-Backbone-React.html)
## Using facebook's React with require.js
[Mario Mueller](http://blog.xenji.com/) wrote a menu component in React and was able to easily integrate it with require.js, EventEmitter2 and bower.
> I recently stumbled upon facebook's React library, which is a Javascript library for building reusable frontend components. Even if this lib is only at version 0.3.x it behaves very stable, it is fast and is fun to code. I'm a big fan of require.js, so I tried to use React within the require.js eco system. It was not as hard as expected and here are some examples and some thoughts about it.
>
> [Read the full post...](http://blog.xenji.com/2013/06/facebooks-react-require-js.html)
## Origins of React
[Pete Hunt](http://www.petehunt.net/blog/) explained what differentiates React from other JavaScript libraries in [a previous blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html). [Lee Byron](http://leebyron.com/) gives another perspective on Quora:
> React isn't quite like any other popular Javascript libraries, and it solves a very specific problem: complex UI rendering. It's also intended to be used along side many other popular libraries. For example, React works well with Backbone.js, amongst many others.
>
> React was born out of frustrations with the common pattern of writing two-way data bindings in complex MVC apps. React is an implementation of one-way data bindings.
>
> [Read the full post...](http://www.quora.com/React-JS-Library/How-is-Facebooks-React-JavaScript-library/answer/Lee-Byron?srid=3DcX)
Since the launch we have received a lot of feedback and are actively working on React 0.4. In the meantime, here are the highlights of this week.
## Some quick thoughts on React
[Andrew Greig](http://www.andrewgreig.com/) made a blog post that gives a high level description of what React is.
> I have been using Facebooks recently released Javascript framework called React.js for the last few days and have managed to obtain a rather high level understanding of how it works and formed a good perspective on how it fits in to the entire javascript framework ecosystem.
>
> Basically, React is not an MVC framework. It is not a replacement for Backbone or Knockout or Angular, instead it is designed to work with existing frameworks and help extend their functionality.
>
> It is designed for building big UIs. The type where you have lots of reusable components that are handling events and presenting and changing some backend data. In a traditional MVC app, React fulfils the role of the View. So you would still need to handle the Model and Controller on your own.
>
> I found the best way to utilise React was to pair it with Backbone, with React replacing the Backbone View, or to write your own Model/Data object and have React communicate with that.
>
> [Read the full post...](http://www.andrewgreig.com/637/)
## React and Socket.IO Chat Application
[Danial Khosravi](http://danialk.github.io/) made a real-time chat application that interacts with the back-end using Socket.IO.
> A week ago I was playing with AngularJS and [this little chat application](https://github.com/btford/angular-socket-io-im) which uses socket.io and nodejs for realtime communication. Yesterday I saw a post about ReactJS in [EchoJS](http://www.echojs.com/) and started playing with this UI library. After playing a bit with React, I decided to write and chat application using React and I used Bran Ford's Backend for server side of this little app.
> [Read the full post...](http://danialk.github.io/blog/2013/06/16/reactjs-and-socket-dot-io-chat-application/)
## React and Other Frameworks
[Pete Hunt](http://www.petehunt.net/blog/) wrote an answer on Quora comparing React and Angular directives. At the end, he explains how you can make an Angular directive that is in fact being rendered with React.
> To set the record straight: React components are far more powerful than Angular templates; they should be compared with Angular's directives instead. So I took the first Google hit for "AngularJS directive tutorial" (AngularJS Directives Tutorial - Fundoo Solutions), rewrote it in React and compared them. [...]
>
> We've designed React from the beginning to work well with other libraries. Angular is no exception. Let's take the original Angular example and use React to implement the fundoo-rating directive.
>
> [Read the full post...](http://www.quora.com/Pete-Hunt/Posts/Facebooks-React-vs-AngularJS-A-Closer-Look)
In the same vein, [Markov Twain](https://twitter.com/markov_twain/status/345702941845499906) re-implemented the examples on the front-page [with Ember](http://jsbin.com/azihiw/2/edit) and [Vlad Yazhbin](https://twitter.com/vla) re-implemented the tutorial [with Angular](http://jsfiddle.net/vla/Cdrse/).
## Web Components: React & x-tags
Mozilla and Google are actively working on Web Components. [Vjeux](http://blog.vjeux.com/) wrote a proof of concept that shows how to implement them using React.
> Using [x-tags](http://www.x-tags.org/) from Mozilla, we can write custom tags within the DOM. This is a great opportunity to be able to write reusable components without being tied to a particular library. I wrote [x-react](https://github.com/vjeux/react-xtags/) to have them being rendered in React.
> [Read the full post...](http://blog.vjeux.com/2013/javascript/custom-components-react-x-tags.html)
## React TodoMVC Example
[TodoMVC.com](http://todomvc.com/) is a website that collects various implementations of the same basic Todo app. [Pete Hunt](http://www.petehunt.net/blog/) wrote an idiomatic React version.
> Developers these days are spoiled with choice when it comes to selecting an MV* framework for structuring and organizing their JavaScript web apps.
>
> To help solve this problem, we created TodoMVC - a project which offers the same Todo application implemented using MV* concepts in most of the popular JavaScript MV* frameworks of today.
> [Read the source code...](https://github.com/tastejs/todomvc/tree/gh-pages/labs/architecture-examples/react)
## JSX is not HTML
Many of you pointed out differences between JSX and HTML. In order to clear up some confusion, we have added some documentation that covers the four main differences:
We have a ton of great stuff coming in v0.4, but in the meantime we're releasing v0.3.3. This release addresses some small issues people were having and simplifies our tools to make them easier to use.
## react-tools
* Upgrade Commoner so `require` statements are no longer relativized when passing through the transformer. This was a feature needed when building React, but doesn't translate well for other consumers of `bin/jsx`.
* Upgraded our dependencies on Commoner and Recast so they use a different directory for their cache.
* Freeze our esprima dependency.
## React
* Allow reusing the same DOM node to render different components. e.g. `React.renderComponent(<div/>, domNode); React.renderComponent(<span/>, domNode);` will work now.
## JSXTransformer
* Improved the in-browser transformer so that transformed scripts will execute in the expected scope. The allows components to be defined and used from separate files.
The highlight of this week is that an interaction-heavy app has been ported to React. React components are solving issues they had with nested views.
## Moving From Backbone To React
[Clay Allsopp](http://twitter.com/clayallsopp) successfully ported [Propeller](http://usepropeller.com/blog/posts/from-backbone-to-react/), a fairly big, interaction-heavy JavaScript app, to React.
> [<img style="float: right; margin: 0 0 10px 10px;" src="/react/img/blog/propeller-logo.png" />](http://usepropeller.com/blog/posts/from-backbone-to-react/)Subviews involve a lot of easy-to-forget boilerplate that Backbone (by design) doesn't automate. Libraries like Backbone.Marionette offer more abstractions to make view nesting easier, but they're all limited by the fact that Backbone delegates how and went view-document attachment occurs to the application code.
>
> React, on the other hand, manages the DOM and only exposes real nodes at select points in its API. The "elements" you code in React are actually objects which wrap DOM nodes, not the actual objects which get inserted into the DOM. Internally, React converts those abstractions into actual DOMElements and fills out the document accordingly. [...]
>
> We moved about 20 different Backbone view classes to React over the past few weeks, including the live-preview pane that you see in our little iOS demo. Most importantly, it's allowed us to put energy into making each component work great on its own, instead of spending extra cycles to ensure they function in unison. For that reason, we think React is a more scalable way to build view-intensive apps than Backbone alone, and it doesn't require you to drop-everything-and-refactor like a move to Ember or Angular would demand.
>
> [Read the full post...](http://usepropeller.com/blog/posts/from-backbone-to-react/)
## Grunt Task for JSX
[Eric Clemmons](http://ericclemmons.github.io/) wrote a task for [Grunt](http://gruntjs.com/) that applies the JSX transformation to your Javascript files. It also works with [Browserify](http://browserify.org/) if you want all your files to be concatenated and minified together.
> Grunt task for compiling Facebook React's .jsx templates into .js
> [Check out the project ...](https://github.com/ericclemmons/grunt-react)
## Backbone/Handlebars Nested Views
[Joel Burget](http://joelburget.com/) wrote a blog post talking about the way we would write React-like components in Backbone and Handlebars.
> The problem here is that we're trying to maniplate a tree, but there's a textual layer we have to go through. Our views are represented as a tree - the subviews are children of CommentCollectionView - and they end up as part of a tree in the DOM. But there's a Handlebars layer in the middle (which deals in flat strings), so the hierarchy must be destructed and rebuilt when we render.
>
> What does it take to render a collection view? In the Backbone/Handlebars view of the world you have to render the template (with stubs), render each subview which replaces a stub, and keep a reference to each subview (or anything within the view that could change in the future).
>
> So while our view is conceptually hierarchical, due to the fact that it has to go through a flat textual representation, we need to do a lot of extra work to reassemble that structure after rendering.
>
> [Read the full post...](http://joelburget.com/react/)
## JSRomandie Meetup
[Renault John Lecoultre](https://twitter.com/renajohn/) from [BugBuster](http://www.bugbuster.com) did a React introduction talk at a JS meetup called [JS Romandie](https://twitter.com/jsromandie) last week.
[Vjeux](http://blog.vjeux.com/) used the fact that JSX is just a syntactic sugar on-top of regular JS to rewrite the React front-page examples in CoffeeScript.
> Multiple people asked what's the story about JSX and CoffeeScript. There is no JSX pre-processor for CoffeeScript and I'm not aware of anyone working on it. Fortunately, CoffeeScript is pretty expressive and we can play around the syntax to come up with something that is usable.
> [Read the full post...](http://blog.vjeux.com/2013/javascript/react-coffeescript.html)
## Tutorial in Plain Javascript
We've seen a lot of people comparing React with various frameworks. [Ricardo Tomasi](http://ricardo.cc/) decided to re-implement the tutorial without any framework, just plain Javascript.
> Facebook & Instagram launched the React framework and an accompanying tutorial. Developer Vlad Yazhbin decided to rewrite that using AngularJS. The end result is pretty neat, but if you're like me you will not actually appreciate the HTML speaking for itself and doing all the hard work. So let's see what that looks like in plain javascript.
>
> [Read the full post...](http://ricardo.cc/2013/06/07/react-tutorial-rewritten-in-plain-javascript.html)
React v0.4 is very close to completion. As we finish it off, we'd like to share with you some of the major changes we've made since v0.3. This is the first of several posts we'll be making over the next week.
## What is React.autoBind?
If you take a look at most of our current examples, you'll see us using `React.autoBind` for event handlers. This is used in place of `Function.prototype.bind`. Remember that in JS, [function calls are late-bound](http://bonsaiden.github.io/JavaScript-Garden/#function.this). That means that if you simply pass a function around, the `this` used inside won't necessarily be the `this` you expect. `Function.prototype.bind` creates a new, properly bound, function so that when called, `this` is exactly what you expect it to be.
Before we launched React, we would write this:
```js{4}
React.createClass({
onClick: function(event) {/* do something with this */},
We wrote `React.autoBind` as a way to cache the function creation and save on memory usage. Since `render` can get called multiple times, if you used `this.onClick.bind(this)` you would actually create a new function on each pass. With React v0.3 you were able to write this instead:
```js{2,4}
React.createClass({
onClick: React.autoBind(function(event) {/* do something with this */}),
render: function() {
return <button onClick={this.onClick} />;
}
});
```
## What's Changing in v0.4?
After using `React.autoBind` for a few weeks, we realized that there were very few times that we didn't want that behavior. So we made it the default! Now all methods defined within `React.createClass` will already be bound to the correct instance.
Starting with v0.4 you can just write this:
```js{2,4}
React.createClass({
onClick: function(event) {/* do something with this */},
render: function() {
return <button onClick={this.onClick} />;
}
});
```
For v0.4 we will simply be making `React.autoBind` a no-op — it will just return the function you pass to it. Most likely you won't have to change your code to account for this change, though we encourage you to update. We'll publish a migration guide documenting this and other changes that come along with React v0.4.
React reconciliation process appears to be very well suited to implement a text editor with a live preview as people at Khan Academy show us.
## Khan Academy
[Ben Kamens](http://bjk5.com/) explains how [Ben Alpert](http://benalpert.com/) and [Joel Burget](http://joelburget.com/) are promoting React inside of [Khan Academy](https://www.khanacademy.org/). They now have three projects in the works using React.
> Recently two Khan Academy devs dropped into our team chat and said they were gonna use React to write a new feature. They even hinted that we may want to adopt it product-wide.
>
> "The library is only a week old. It's a brand new way of thinking about things. We're the first to use it outside of Facebook. Heck, even the React devs were surprised to hear we're using this in production!!!"
>
> [Read the full post...](http://bjk5.com/post/53742233351/getting-your-team-to-adopt-new-technology)
The best part is the demo of how React reconciliation process makes live editing more user-friendly.
> Our renderer, post-React, is on the left. A typical math editor's preview is on the right.
Over the past several weeks, members of our team, [Pete Hunt](http://www.petehunt.net/) and [Paul O'Shannessy](http://zpao.com/), answered many questions that were asked in the [React group](https://groups.google.com/forum/#!forum/reactjs). They give a good overview of how to integrate React with other libraries and APIs through the use of [Mixins](/react/docs/reusable-components.html) and [Lifecycle Methods](/react/docs/working-with-the-browser.html).
> * [JSFiddle](http://jsfiddle.net/aabeL/1/): Basically I've given you two mixins. The first lets you react to global scroll events. The second is, IMO, much more useful: it gives you scroll start and scroll end events, which you can use with setState() to create components that react based on whether the user is scrolling or not.
> * [Gist](https://gist.github.com/zpao/5686416): The big thing to notice is that my component is pretty dumb (it doesn't have to be but that's how I chose to model it). All it does is render itself based on the props that are passed in. renderOrUpdate is where the "magic" happens.
> * [Gist](https://gist.github.com/petehunt/5687230): This example is doing everything -- including the IO -- inside of a single React component.
> * [Gist](https://gist.github.com/petehunt/5687276): One pattern that we use at Instagram a lot is to employ separation of concerns and consolidate I/O and state into components higher in the hierarchy to keep the rest of the components mostly stateless and purely display.
> * [JSFiddle](http://jsfiddle.net/LQxy7/): Your React component simply render empty divs, and then in componentDidMount() you call React.renderComponent() on each of those divs to set up a new root React tree. Be sure to explicitly unmountAndReleaseReactRootNode() for each component in componentWillUnmount().
## Introduction to React Screencast
[Pete Hunt](http://www.petehunt.net/) recorded himself implementing a simple `<Blink>` tag in React.
title: "New in React v0.4: Prop Validation and Default Values"
layout: post
author: Paul O'Shannessy
---
Many of the questions we got following the public launch of React revolved around `props`, specifically that people wanted to do validation and to make sure their components had sensible defaults.
## Validation
Oftentimes you want to validate your `props` before you use them. Perhaps you want to ensure they are a specific type. Or maybe you want to restrict your prop to specific values. Or maybe you want to make a specific prop required. This was always possible — you could have written validations in your `render` or `componentWillReceiveProps` functions, but that gets clunky fast.
React v0.4 will provide a nice easy way for you to use built-in validators, or to even write your own.
One common pattern we've seen with our React code is to do something like this:
```js
React.createClass({
render:function(){
varvalue=this.props.value||'default value';
return<div>{value}</div>;
}
});
```
Do this for a few `props` across a few components and now you have a lot of redundant code. Starting with React v0.4, you can provide default values in a declarative way:
```js
React.createClass({
getDefaultProps:function(){
return{
value:'default value'
};
}
...
});
```
We will use the cached result of this function before each `render`. We also perform all validations before each `render` to ensure that you have all of the data you need in the right form before you try to use it.
- - -
Both of these features are entirely optional. We've found them to be increasingly valuable at Facebook as our applications grow and evolve, and we hope others find them useful as well.
Over the past 2 months we've been taking feedback and working hard to make React even better. We fixed some bugs, made some under-the-hood improvements, and added several features that we think will improve the experience developing with React. Today we're proud to announce the availability of React v0.4!
This release could not have happened without the support of our growing community. Since launch day, the community has contributed blog posts, questions to the [Google Group](http://groups.google.com/group/reactjs), and issues and pull requests on GitHub. We've had contributions ranging from documentation improvements to major changes to React's rendering. We've seen people integrate React into the tools they're using and the products they're building, and we're all very excited to see what our budding community builds next!
React v0.4 has some big changes. We've also restructured the documentation to better communicate how to use React. We've summarized the changes below and linked to documentation where we think it will be especially useful.
When you're ready, [go download it](/react/downloads.html)!
### React
* Switch from using `id` attribute to `data-reactid` to track DOM nodes. This allows you to integrate with other JS and CSS libraries more easily.
* Support for more DOM elements and attributes (e.g., `<canvas>`)
* Improved server-side rendering APIs. `React.renderComponentToString(<component>, callback)` allows you to use React on the server and generate markup which can be sent down to the browser.
*`prop` improvements: validation and default values. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/11/react-v0-4-prop-validation-and-default-values.html)
* Support for the `key` prop, which allows for finer control over reconciliation. [Read the docs for details...](http://facebook.github.io/react/docs/multiple-components.html)
* Removed `React.autoBind`. [Read our blog post for details...](http://facebook.github.io/react/blog/2013/07/02/react-v0-4-autobind-by-default.html)
* Improvements to forms. We've written wrappers around `<input>`, `<textarea>`, `<option>`, and `<select>` in order to standardize many inconsistencies in browser implementations. This includes support for `defaultValue`, and improved implementation of the `onChange` event, and circuit completion. [Read the docs for details...](http://facebook.github.io/react/docs/forms.html)
* We've implemented an improved synthetic event system that conforms to the W3C spec.
* Updates to your component are batched now, which may result in a significantly faster re-render of components. `this.setState` now takes an optional callback as its second parameter. If you were using `onClick={this.setState.bind(this, state)}` previously, you'll want to make sure you add a third parameter so that the event is not treated as the callback.
### JSX
* Support for comment nodes `<div>{/* this is a comment and won't be rendered */}</div>`
* Children are now transformed directly into arguments instead of being wrapped in an array
E.g. `<div><Component1/><Component2/></div>` is transformed into `React.DOM.div(null, Component1(null), Component2(null))`.
Previously this would be transformed into `React.DOM.div(null, [Component1(null), Component2(null)])`.
If you were using React without JSX previously, your code should still work.
### react-tools
* Fixed a number of bugs when transforming directories
* No longer re-write `require()`s to be relative unless specified
We launched the [React Facebook Page](https://www.facebook.com/react) along with the React v0.4 launch. 700 people already liked it to get updated on the project :)
## Cross-browser onChange
[Ben Alpert](http://benalpert.com/) from [Khan Academy](https://www.khanacademy.org/) worked on a cross-browser implementation of `onChange` event that landed in v0.4. He wrote a blog post explaining the various browser quirks he had to deal with.
> First off, what is the input event? If you have an `<input>` element and want to receive events whenever the value changes, the most obvious thing to do is to listen to the change event. Unfortunately, change fires only after the text field is defocused, rather than on each keystroke. The next obvious choice is the keyup event, which is triggered whenever a key is released. Unfortunately, keyup doesn't catch input that doesn't involve the keyboard (e.g., pasting from the clipboard using the mouse) and only fires once if a key is held down, rather than once per inserted character.
>
> Both keydown and keypress do fire repeatedly when a key is held down, but both fire immediately before the value changes, so to read the new value you have to defer the handler to the next event loop using `setTimeout(fn, 0)` or similar, which slows down your app. Of course, like keyup, neither keydown nor keypress fires for non-keyboard input events, and all three can fire in cases where the value doesn't change at all (such as when pressing the arrow keys).
>
> [Read the full post...](http://benalpert.com/2013/06/18/a-near-perfect-oninput-shim-for-ie-8-and-9.html)
## React Samples
Learning a new library is always easier when you have working examples you can play with. [jwh](https://github.com/jhw) put many of them on his [react-samples Github repo](https://github.com/jhw/react-samples).
> Some simple examples with Facebook's React framework
>
> * Bootstrap action bar, modal and table [#1](https://rawgithub.com/jhw/react-samples/master/html/actionbar.html),
[Cheng Lou](https://github.com/chenglou) wrote a wrapper for the [Chosen](http://harvesthq.github.io/chosen/) input library called [react-chosen](https://github.com/chenglou/react-chosen). It took just 25 lines to be able to use jQuery component as a React one.
[Domenic Denicola](http://domenicdenicola.com/) wrote a slide deck about the great applications of ES6 features and one slide shows how we could use Template Strings to compile JSX at run-time without the need for a pre-processing phase.
[Tom Occhino](http://tomocchino.com/) and [Jordan Walke](https://github.com/jordwalke), React developers, did a presentation of React at Facebook Seattle's office. Check out the first 25 minutes for the presentation and the remaining 45 for a Q&A. I highly recommend you watching this video.
[Pete Hunt](http://www.petehunt.net/) rewrote the entirety of the docs for v0.4. The goal was to add more explanation about why we built React and what the best practices are.
React v0.4.1 is a small update, mostly containing correctness fixes. Some code has been restructured internally but those changes do not impact any of our public APIs.
## React
*`setState` callbacks are now executed in the scope of your component.
*`click` events now work on Mobile Safari.
* Prevent a potential error in event handling if `Object.prototype` is extended.
* Don't set DOM attributes to the string `"undefined"` on update when previously defined.
* Improved support for `<iframe>` attributes.
* Added checksums to detect and correct cases where server-side rendering markup mismatches what React expects client-side.
## JSXTransformer
* Improved environment detection so it can be run in a non-browser environment.
Today we're releasing a gem to make it easier to use React and JSX in Ruby on Rails applications: [react-rails](https://github.com/facebook/react-rails).
This gem has 2 primary purposes:
1. To package `react.js` in a way that's easy to use and easy to update.
2. To allow you to write JSX without an external build step to transform that into JS.
## Packaging react.js
To make `react.js` available for use client-side, simply add `react` to your manifest, and declare the variant you'd like to use in your environment. When you use `:production`, the minified and optimized `react.min.js` will be used instead of the development version. For example:
```ruby
# config/environments/development.rb
MyApp::Application.configuredo
config.react.variant=:development
# use :production in production.rb
end
```
```js
// app/assets/javascript/application.js
//= require react
```
## Writing JSX
When you name your file with `myfile.js.jsx`, `react-rails` will automatically try to transform that file. For the time being, we still require that you include the docblock at the beginning of the file. For example, this file will get transformed on request.
`react-rails` takes advantage of the [asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) that was introduced in Rails 3.1. A very important part of that pipeline is the `assets:precompile` Rake task. `react-rails` will ensure that your JSX files will be transformed into regular JS before all of your assets are minified and packaged.
## Installation
Installation follows the same process you're familiar with. You can install it globally with `gem install react-rails`, though we suggest you add the dependency to your `Gemfile` directly.
This is the first Community Round-up where none of the items are from Facebook/Instagram employees. It's great to see the adoption of React growing.
## React Game Tutorial
[Caleb Cassel](https://twitter.com/CalebCassel) wrote a [step-by-step tutorial](https://rawgithub.com/calebcassel/react-demo/master/part1.html) about making a small game. It covers JSX, State and Events, Embedded Components and Integration with Backbone.
[Andrey Popp](http://andreypopp.com/) created a [Browserify](http://browserify.org/) helper to compile JSX files.
> Browserify v2 transform for `text/jsx`. Basic usage is:
>
> ```
% browserify -t reactify main.jsx
```
>
> `reactify` transform activates for files with either `.jsx` extension or `/** @jsx React.DOM */` pragma as a first line for any `.js` file.
>
> [Check it out on Github...](https://github.com/andreypopp/reactify)
## React Integration with Este
[Daniel Steigerwald](http://daniel.steigerwald.cz/) is now using React within [Este](https://github.com/steida/este), which is a development stack for web apps in CoffeeScript that are statically typed using the Closure Library.
[Check it out on Github...](https://github.com/steida/este-library/blob/master/este/demos/thirdparty/react/start.coffee)
## React Stylus Boilerplate
[Zaim Bakar](http://zaim.github.io/) shared his boilerplate to get started with Stylus CSS processor.
> This is my boilerplate React project using Grunt as the build tool, and Stylus as my CSS preprocessor.
>
> - Very minimal HTML boilerplate
> - Uses Stylus, with nib included
> - Uses two build targets:
> - `grunt build` to compile JSX and Stylus into a development build
> - `grunt dist` to minify and optimize the development build for production
>
> [Check it out on Github...](https://github.com/zaim/react-stylus-boilerplate)
## WebFUI
[Conrad Barski](http://lisperati.com/), author of the popular book [Land of Lisp](http://landoflisp.com/), wants to use React for his ClojureScript library called [WebFUI](https://github.com/drcode/webfui).
> I'm the author of "[Land of Lisp](http://landoflisp.com/)" and I love your framework. I built a somewhat similar framework a year ago [WebFUI](https://github.com/drcode/webfui) aimed at ClojureScript. My framework also uses global event delegates, a global "render" function, DOM reconciliation, etc just like react.js. (Of course these ideas all have been floating around the ether for ages, always great to see more people building on them.)
>
> Your implementation is more robust, and so I think the next point release of webfui will simply delegate all the "hard work" to react.js and will only focus on the areas where it adds value (enabling purely functional UI programming in clojurescript, and some other stuff related to streamlining event handling)
Today we're happy to announce the initial release of [PyReact](https://github.com/facebook/react-python), which makes it easier to use React and JSX in your Python applications. It's designed to provide an API to transform your JSX files into JavaScript, as well as provide access to the latest React source files.
## Usage
Transform your JSX files via the provided `jsx` module:
```python
fromreactimportjsx
# For multiple paths, use the JSXTransformer class.
transformer=jsx.JSXTransformer()
forjsx_path,js_pathinmy_paths:
transformer.transform(jsx_path,js_path)
# For a single file, you can use a shortcut method.
For full paths to React files, use the `source` module:
```python
fromreactimportsource
# path_for raises IOError if the file doesn't exist.
react_js=source.path_for('react.min.js')
```
## Django
PyReact includes a JSX compiler for [django-pipeline](https://github.com/cyberdelia/django-pipeline). Add it to your project's pipeline settings like this:
```python
PIPELINE_COMPILERS=(
'react.utils.pipeline.JSXCompiler',
)
```
## Installation
PyReact is hosted on PyPI, and can be installed with `pip`:
$ pip install PyReact
Alternatively, add it into your `requirements` file:
PyReact==0.1.1
**Dependencies**: PyReact uses [PyExecJS](https://github.com/doloopwhile/PyExecJS) to execute the bundled React code, which requires that a JS runtime environment is installed on your machine. We don't explicitly set a dependency on a runtime environment; Mac OS X comes bundled with one. If you're on a different platform, we recommend [PyV8](https://code.google.com/p/pyv8/).
For the initial release, we've only tested on Python 2.7. Look out for support for Python 3 in the future, and if you see anything that can be improved, we welcome your [contributions](https://github.com/facebook/react-python/blob/master/CONTRIBUTING.md)!
* [15 blog posts](http://facebook.github.io/react/blog/)
* 2 early adopters: [Khan Academy](http://benalpert.com/2013/06/09/using-react-to-speed-up-khan-academy.html) and [Propeller](http://usepropeller.com/blog/posts/from-backbone-to-react/)
## Wolfenstein Rendering Engine Ported to React
[Pete Hunt](http://www.petehunt.net/) ported the render code of the web version of Wolfenstein 3D to React. Check out [the demo](http://www.petehunt.net/wolfenstein3D-react/wolf3d.html) and [render.js](https://github.com/petehunt/wolfenstein3D-react/blob/master/js/renderer.js#L183) file for the implementation.
[Ben Newman](https://twitter.com/benjamn) made a [13-lines wrapper](https://github.com/benjamn/meteor-react/blob/master/lib/mixin.js) to use React and Meteor together. [Meteor](http://www.meteor.com/) handles the real-time data synchronization between client and server. React provides the declarative way to write the interface and only updates the parts of the UI that changed.
> This repository defines a Meteor package that automatically integrates the React rendering framework on both the client and the server, to complement or replace the default Handlebars templating system.
>
> The React core is officially agnostic about how you fetch and update your data, so it is far from obvious which approach is the best. This package provides one answer to that question (use Meteor!), and I hope you will find it a compelling combination.
>
>```javascript
>var MyComponent = React.createClass({
> mixins: [MeteorMixin],
>
> getMeteorState: function() {
> return { foo: Session.get('foo') };
> },
>
> render: function() {
> return <div>{this.state.foo}</div>;
> }
>});
>```
>
> Dependencies will be registered for any data accesses performed by getMeteorState so that the component can be automatically re-rendered whenever the data changes.
>
> [Read more ...](https://github.com/benjamn/meteor-react)
## React Page
[Jordan Walke](https://github.com/jordwalke) implemented a complete React project creator called [react-page](https://github.com/facebook/react-page/). It supports both server-side and client-side rendering, source transform and packaging JSX files using CommonJS modules, and instant reload.
> Easy Application Development with React JavaScript
> * Markup displayed before downloading large JavaScript.
> * Markup can be generated more quickly on a fast server than low power client devices.
> * Faster Development and Prototyping:
> * Instantly refresh your app without waiting for any watch scripts or bundlers.
> * Easy deployment of static content pages/blogs: just archive using recursive wget.
> * SEO benefits of indexability and perf.
>
> **How Does Server Rendering Work?**
>
> * `react-page` computes page markup on the server, sends it to the client so the user can see it quickly.
> * The corresponding JavaScript is then packaged and sent.
> * The browser runs that JavaScript, so that all of the event handlers, interactions and update code will run seamlessly on top of the server generated markup.
> * From the developer's (and the user's) perspective, it's just as if the rendering occurred on the client, only faster.
>
> [Try it out ...](https://github.com/facebook/react-page/)
A lot has happened in the month since our last update. Here are some of the more interesting things we've found. But first, we have a couple updates before we share links.
First, we are organizing a [React Hackathon](http://reactjshack-a-thon.splashthat.com/) in Facebook's Seattle office on Saturday September 28. If you want to hack on React, meet some of the team or win some prizes, feel free to join us!
We've also reached a point where there are too many questions for us to handle directly. We're encouraging people to ask questions on [StackOverflow](http://stackoverflow.com/questions/tagged/reactjs) using the tag [[reactjs]](http://stackoverflow.com/questions/tagged/reactjs). Many members of the team and community have subscribed to the tag, so feel free to ask questions there. We think these will be more discoverable than Google Groups archives or IRC logs.
## Javascript Jabber
[Pete Hunt](http://www.petehunt.net/) and [Jordan Walke](https://github.com/jordwalke) were interviewed on [Javascript Jabber](http://javascriptjabber.com/073-jsj-react-with-pete-hunt-and-jordan-walke/) for an hour. They go over many aspects of React such as 60 FPS, Data binding, Performance, Diffing Algorithm, DOM Manipulation, Node.js support, server-side rendering, JSX, requestAnimationFrame and the community. This is a gold mine of information about React.
> **PETE:** So React was designed all around that. Conceptually, how you build a React app is that every time your data changes, it's like hitting the refresh button in a server-rendered app. What we do is we conceptually throw out all of the markup and event handlers that you've registered and we reset the whole page and then we redraw the entire page. If you're writing a server-rendered app, handling updates is really easy because you hit the refresh button and you're pretty much guaranteed to get what you expect.
>
> **MERRICK:** That's true. You don't get into these odd states.
>
> **PETE:** Exactly, exactly. In order to implement that, we communicate it as a fake DOM. What we'll do is rather than throw out the actual browser html and event handlers, we have an internal representation of what the page looks like and then we generate a brand new representation of what we want the page to look like. Then we perform this really, really fast diffing algorithm between those two page representations, DOM representations. Then React will compute the minimum set of DOM mutations it needs to make to bring the page up to date.
>
> Then to finally get to answer your question, that set of DOM mutations then goes into a queue and we can plug in arbitrary flushing strategies for that. For example, when we originally launched React in open source, every setState would immediately trigger a flush to the DOM. That wasn't part of the contract of setState, but that was just our strategy and it worked pretty well. Then this totally awesome open source contributor Ben Alpert at Khan Academy built a new batching strategy which would basically queue up every single DOM update and state change that happened within an event tick and would execute them in bulk at the end of the event tick.
>
> [Read the full conversation ...](http://javascriptjabber.com/073-jsj-react-with-pete-hunt-and-jordan-walke/)
## JSXTransformer Trick
While this is not going to work for all the attributes since they are camelCased in React, this is a pretty cool trick.
<div style="margin-left: 74px;"><blockquote class="twitter-tweet"><p>Turn any DOM element into a React.js function: JSXTransformer.transform("/** <a href="https://twitter.com/jsx">@jsx</a> React.DOM */" + element.innerHTML).code</p>— Ross Allen (@ssorallen) <a href="https://twitter.com/ssorallen/statuses/377105575441489920">September 9, 2013</a></blockquote></div>
[Stoyan Stefanov](http://www.phpied.com/) gave a talk at [BrazilJS](http://braziljs.com.br/) about React and wrote an article with the content of the presentation. He goes through the difficulties of writting _active apps_ using the DOM API and shows how React handles it.
> So how does exactly React deal with it internally? Two crazy ideas - virtual DOM and synthetic events.
>
> You define you components in React. It builds a virtual DOM in JavaScript land which is way more efficient. Then it updates the DOM. (And "virtual DOM" is a very big name for what is simply a JavaScript object with nested key-value pairs)
>
> Data changes. React computes a diff (in JavaScript land, which is, of course, much more efficient) and updates the single table cell that needs to change. React replicates the state of the virtual DOM into the actual DOM only when and where it's necessary. And does it all at once, in most cases in a single tick of the `requestAnimationFrame()`.
>
> What about event handlers? They are synthetic. React uses event delegation to listen way at the top of the React tree. So removing a node in the virtual DOM has no effect on the event handling.
>
> The events are automatically cross-browser (they are React events). They are also much closer to W3C than any browser. That means that for example `e.target` works, no need to look for the event object or checking whether it's `e.target` or `e.srcElement` (IE). Bubbling and capturing phases also work cross browser. React also takes the liberty of making some small fixes, e.g. the event `<input onChange>` fires when you type, not when blur away from the input. And of course, event delegation is used as the most efficient way to handle events. You know that "thou shall use event delegation" is also commonly given advice for making web apps snappy.
>
> The good thing about the virtual DOM is that it's all in JavaScript land. You build all your UI in JavaScript. Which means it can be rendered on the server side, so you initial view is fast (and any SEO concerns are addressed). Also, if there are especially heavy operations they can be threaded into WebWorkers, which otherwise have no DOM access.
>
> [Read More ...](http://www.phpied.com/remarkable-react/)
## Markdown in React
[Ben Alpert](http://benalpert.com/) converted [marked](https://github.com/chjj/marked), a Markdown Javascript implementation, in React: [marked-react](https://github.com/spicyj/marked-react). Even without using JSX, the HTML generation is now a lot cleaner. It is also safer as forgetting a call to `escape` will not introduce an XSS vulnerability.
[Renault John Lecoultre](https://twitter.com/renajohn) wrote [Unite](https://www.bugbuster.com/), an interactive tool for analyzing code dynamically using React. It integrates with CodeMirror.
[Vjeux](http://blog.vjeux.com/) re-implemented the display part of the IRC logger in React. Just 130 lines are needed for a performant infinite scroll with timestamps and color-coded author names.
This release is the result of several months of hard work from members of the team and the community. While there are no groundbreaking changes in core, we've worked hard to improve performance and memory usage. We've also worked hard to make sure we are being consistent in our usage of DOM properties.
The biggest change you'll notice as a developer is that we no longer support `class` in JSX as a way to provide CSS classes. Since this prop was being converted to `className` at the transform step, it caused some confusion when trying to access it in composite components. As a result we decided to make our DOM properties mirror their counterparts in the JS DOM API. There are [a few exceptions](https://github.com/facebook/react/blob/master/src/dom/DefaultDOMPropertyConfig.js#L156) where we deviate slightly in an attempt to be consistent internally.
The other major change in v0.5 is that we've added an additional build - `react-with-addons` - which adds support for some extras that we've been working on including animations and two-way binding. [Read more about these addons in the docs](/react/docs/addons.html).
## Thanks to Our Community
We added *22 new people* to the list of authors since we launched React v0.4.1 nearly 3 months ago. With a total of 48 names in our `AUTHORS` file, that means we've nearly doubled the number of contributors in that time period. We've seen the number of people contributing to discussion on IRC, mailing lists, Stack Overflow, and GitHub continue rising. We've also had people tell us about talks they've given in their local community about React.
It's been awesome to see the things that people are building with React, and we can't wait to see what you come up with next!
## Changelog
### React
* Memory usage improvements - reduced allocations in core which will help with GC pauses
* Performance improvements - in addition to speeding things up, we made some tweaks to stay out of slow path code in V8 and Nitro.
* Standardized prop -> DOM attribute process. This previously resulting in additional type checking and overhead as well as confusing cases for users. Now we will always convert your value to a string before inserting it into the DOM.
* Support for Selection events.
* Support for [Composition events](https://developer.mozilla.org/en-US/docs/Web/API/CompositionEvent).
* Support for additional DOM properties (`charSet`, `content`, `form`, `httpEquiv`, `rowSpan`, `autoCapitalize`).
* Support for additional SVG properties (`rx`, `ry`).
* Support for using `getInitialState` and `getDefaultProps` in mixins.
* Support mounting into iframes.
* Bug fixes for controlled form components.
* Bug fixes for SVG element creation.
* Added `React.version`.
* Added `React.isValidClass` - Used to determine if a value is a valid component constructor.
* Removed `React.autoBind` - This was deprecated in v0.4 and now properly removed.
* Renamed `React.unmountAndReleaseReactRootNode` to `React.unmountComponentAtNode`.
* Began laying down work for refined performance analysis.
* Better support for server-side rendering - [react-page](https://github.com/facebook/react-page) has helped improve the stability for server-side rendering.
* Made it possible to use React in environments enforcing a strict [Content Security Policy](https://developer.mozilla.org/en-US/docs/Security/CSP/Introducing_Content_Security_Policy). This also makes it possible to use React to build Chrome extensions.
### React with Addons (New!)
* Introduced a separate build with several "addons" which we think can help improve the React experience. We plan to deprecate this in the long-term, instead shipping each as standalone pieces. [Read more in the docs](/react/docs/addons.html).
### JSX
* No longer transform `class` to `className` as part of the transform! This is a breaking change - if you were using `class`, you *must* change this to `className` or your components will be visually broken.
* Added warnings to the in-browser transformer to make it clear it is not intended for production use.
* Improved compatibility for Windows
* Improved support for maintaining line numbers when transforming.
This release focuses on fixing some small bugs that have been uncovered over the past two weeks. I would like to thank everybody involved, specifically members of the community who fixed half of the issues found. Thanks to [Ben Alpert][1], [Andrey Popp][2], and [Laurence Rowe][3] for their contributions!
## Changelog
### React
* Fixed bug with `<input type="range">` and selection events.
* Fixed bug with selection and focus.
* Made it possible to unmount components from the document root.
* Fixed bug for `disabled` attribute handling on non-`<input>` elements.
### React with Addons
* Fixed bug with transition and animation event detection.
We organized a React hackathon last week-end in the Facebook Seattle office. 50 people, grouped into 15 teams, came to hack for a day on React. It was a lot of fun and we'll probably organize more in the future.
## React Hackathon Winner
[Alex Swan](http://bold-it.com/) implemented [Qu.izti.me](http://qu.izti.me/), a multi-player quiz game. It is real-time via Web Socket and mobile friendly.
> The game itself is pretty simple. People join the "room" by going to [http://qu.izti.me](http://qu.izti.me/) on their device. Large displays will show a leaderboard along with the game, and small displays (such as phones) will act as personal gamepads. Users will see questions and a choice of answers. The faster you answer, the more points you earn.
>
> In my opinion, Socket.io and React go together like chocolate and peanut butter. The page was always an accurate representation of the game object.
[Pete Hunt](http://www.petehunt.net/) presented React at JSConf EU. He covers three controversial design decisions of React:
1. Build **components**, not templates
2. Re-render the whole app on every update
3. Virtual DOM
The video will be available soon on the [JSConf EU website](http://2013.jsconf.eu/speakers/pete-hunt-react-rethinking-best-practices.html), but in the meantime, here are Pete's slides:
[Alexander Solovyov](http://solovyov.net/) has been working on React bindings for ClojureScript. This is really exciting as it is using "native" ClojureScript data structures.
```ruby
(nsyour.app
(:require-macros[pump.def-macros:refer[defr]])
(:require[pump.core]))
(defrComponent
:get-initial-state#(identity {:some-value ""})
[componentpropsstate]
[:div{:class-name"test"}"hello"])
```
[Check it out on GitHub...](https://github.com/piranha/pump)
## JSXHint
[Todd Kennedy](http://blog.selfassembled.org/) working at [Condé Nast](http://www.condenast.com/) implemented a wrapper on-top of [JSHint](http://www.jshint.com/) that first converts JSX files to JS.
> A wrapper around JSHint to allow linting of files containg JSX syntax. Accepts glob patterns. Respects your local .jshintrc file and .gitignore to filter your glob patterns.
>
> ```
npm install -g jsxhint
```
>
> [Check it out on GitHub...](https://github.com/CondeNast/JSXHint)
## Turbo React
[Ross Allen](https://twitter.com/ssorallen) working at [Mesosphere](http://mesosphere.io/) combined [Turbolinks](https://github.com/rails/turbolinks/), a library used by Ruby on Rails to speed up page transition, and React.
> "Re-request this page" is just a link to the current page. When you click it, Turbolinks intercepts the GET request and fetchs the full page via XHR.
>
> The panel is rendered with a random panel- class on each request, and the progress bar gets a random widthX class.
>
> With Turbolinks alone, the entire <body> would be replaced, and transitions would not happen. In this little demo though, React adds and removes classes and text, and the attribute changes are animated with CSS transitions. The DOM is otherwise left intact.
> [Check out the demo...](https://turbo-react.herokuapp.com/)
## Reactive Table
[Stoyan Stefanov](http://www.phpied.com/) continues his series of blog posts about React. This one is an introduction tutorial on rendering a simple table with React.
> React is all about components. So let's build one.
>
> Let's call it Table (to avoid any confusion what the component is about).
>
> ```javascript
var Table = React.createClass({
/*stuff goeth here*/
});
```
>
> You see that React components are defined using a regular JS object. Some properties and methods of the object such as render() have special meanings, the rest is upforgrabs.
>
> [Read the full article...](http://www.phpied.com/reactive-table/)
React is, in my opinion, the premier way to build big, fast Web apps with JavaScript. It's scaled very well for us at Facebook and Instagram.
One of the many great parts of React is how it makes you think about apps as you build them. In this post I'll walk you through the thought process of building a searchable product data table using React.
## Start with a mock
Imagine that we already have a JSON API and a mock from our designer. Our designer apparently isn't very good because the mock looks like this:
## Step 1: break the UI into a component hierarchy
The first thing you'll want to do is to draw boxes around every component (and subcomponent) in the mock and give them all names. If you're working with a designer they may have already done this, so go talk to them! Their Photoshop layer names may end up being the names of your React components!
But how do you know what should be its own component? Just use the same techniques for deciding if you should create a new function or object. One such technique is the [single responsibility principle](http://en.wikipedia.org/wiki/Single_responsibility_principle), that is, a component should ideally only do one thing. If it ends up growing it should be decomposed into smaller subcomponents.
Since you're often displaying a JSON data model to a user, you'll find that if your model was built correctly your UI (and therefore your component structure) will map nicely onto it. That's because user interfaces and data models tend to adhere to the same *information architecture* which means the work of separating your UI into components is often trivial. Just break it up into components that represent exactly one piece of your data model.
You'll see here that we have five components in our simple app. I've italicized the data each component represents.
1.**`FilterableProductTable` (orange):** contains the entirety of the example
2.**`SearchBar` (blue):** receives all *user input*
3.**`ProductTable` (green):** displays and filters the *data collection* based on *user input*
4.**`ProductCategoryRow` (turquoise):** displays a heading for each *category*
5.**`ProductRow` (red):** displays a row for each *product*
If you look at `ProductTable` you'll see that the table header (containing the "Name" and "Price" labels) isn't its own component. This is a matter of preference and there's an argument to be made either way. For this example I left it as part of `ProductTable` because it is part of rendering the *data collection* which is `ProductTable`'s responsibility. However if this header grows to be complex (i.e. if we were to add affordances for sorting) it would certainly make sense to make this its own `ProductTableHeader` component.
Now that we've identified the components in our mock, let's arrange them into a hierarchy. This is easy. Components that appear within another component in the mock should appear as a child in the hierarchy:
Now that you have your component hierarchy it's time to start implementing your app. The easiest way is to build a version that takes your data model and renders the UI but has no interactivity. It's easiest to decouple these processes because building a static version requires a lot of typing and no thinking, and adding interactivity requires a lot of thinking and not a lot of typing. We'll see why.
To build a static version of your app that renders your data model you'll want to build components that reuse other components and pass data using *props*. *props* are a way of passing data from parent to child. If you're familiar with the concept of *state*, **don't use state at all** to build this static version. State is reserved only for interactivity, that is, data that changes over time. Since this is a static version of the app you don't need it.
You can build top-down or bottom-up. That is, you can either start with building the components higher up in the hierarchy (i.e. starting with `FilterableProductTable`) or with the ones lower in it (`ProductRow`). In simpler examples it's usually easier to go top-down and on larger projects it's easier to go bottom-up and write tests as you build.
At the end of this step you'll have a library of reusable components that render your data model. The components will only have `render()` methods since this is a static version of your app. The component at the top of the hierarchy (`FilterableProductTable`) will take your data model as a prop. If you make a change to your underlying data model and call `renderComponent()` again the UI will be updated. It's easy to see how your UI is updated and where to make changes since there's nothing complicated going on since React's **one-way data flow** (also called *one-way binding*) keeps everything modular, easy to reason about, and fast.
Simply refer to the [React docs](http://facebook.github.io/react/docs/) if you need help executing this step.
### A brief interlude: props vs state
There are two types of "model" data in React: props and state. It's important to understand the distinction between the two; skim [the official React docs](http://facebook.github.io/react/docs/interactivity-and-dynamic-uis.html) if you aren't sure what the difference is.
## Step 3: Identify the minimal (but complete) representation of UI state
To make your UI interactive you need to be able to trigger changes to your underlying data model. React makes this easy with **state**.
To build your app correctly you first need to think of the minimal set of mutable state that your app needs. The key here is DRY: *Don't Repeat Yourself*. Figure out what the absolute minimal representation of the state of your application needs to be and compute everything else you need on-demand. For example, if you're building a TODO list, just keep an array of the TODO items around; don't keep a separate state variable for the count. Instead, when you want to render the TODO count simply take the length of the TODO items array.
Think of all of the pieces of data in our example application. We have:
* The original list of products
* The search text the user has entered
* The value of the checkbox
* The filtered list of products
Let's go through each one and figure out which one is state. Simply ask three questions about each piece of data:
1. Is it passed in from a parent via props? If so, it probably isn't state.
2. Does it change over time? If not, it probably isn't state.
3. Can you compute it based on any other state or props in your component? If so, it's not state.
The original list of products is passed in as props, so that's not state. The search text and the checkbox seem to be state since they change over time and can't be computed from anything. And finally, the filtered list of products isn't state because it can be computed by combining the original list of products with the search text and value of the checkbox.
OK, so we've identified what the minimal set of app state is. Next we need to identify which component mutates, or *owns*, this state.
Remember: React is all about one-way data flow down the component hierarchy. It may not be immediately clear which component should own what state. **This is often the most challenging part for newcomers to understand,** so follow these steps to figure it out:
For each piece of state in your application:
* Identify every component that renders something based on that state.
* Find a common owner component (a single component above all the components that need the state in the hierarchy).
* Either the common owner or another component higher up in the hierarchy should own the state.
* If you can't find a component where it makes sense to own the state, create a new component simply for holding the state and add it somewhere in the hierarchy above the common owner component.
Let's run through this strategy for our application:
*`ProductTable` needs to filter the product list based on state and `SearchBar` needs to display the search text and checked state.
* The common owner component is `FilterableProductTable`.
* It conceptually makes sense for the filter text and checked value to live in `FilterableProductTable`
Cool, so we've decided that our state lives in `FilterableProductTable`. First, add a `getInitialState()` method to `FilterableProductTable` that returns `{filterText: '', inStockOnly: false}` to reflect the initial state of your application. Then pass `filterText` and `inStockOnly` to `ProductTable` and `SearchBar` as a prop. Finally, use these props to filter the rows in `ProductTable` and set the values of the form fields in `SearchBar`.
You can start seeing how your application will behave: set `filterText` to `"ball"` and refresh your app. You'll see the data table is updated correctly.
So far we've built an app that renders correctly as a function of props and state flowing down the hierarchy. Now it's time to support data flowing the other way: the form components deep in the hierarchy need to update the state in `FilterableProductTable`.
React makes this data flow explicit to make it easy to understand how your program works, but it does require a little more typing than traditional two-way data binding. React provides an add-on called `ReactLink` to make this pattern as convenient as two-way binding, but for the purpose of this post we'll keep everything explicit.
If you try to type or check the box in the current version of the example you'll see that React ignores your input. This is intentional, as we've set the `value` prop of the `input` to always be equal to the `state` passed in from `FilterableProductTable`.
Let's think about what we want to happen. We want to make sure that whenever the user changes the form we update the state to reflect the user input. Since components should only update their own state, `FilterableProductTable` will pass a callback to `SearchBar` that will fire whenever the state should be updated. We can use the `onChange` event on the inputs to be notified of it. And the callback passed by `FilterableProductTable` will call `setState()` and the app will be updated.
Though this sounds like a lot it's really just a few lines of code. And it's really explicit how your data is flowing throughout the app.
## And that's it
Hopefully this gives you an idea of how to think about building components and applications with React. While it may be a little more typing than you're used to, remember that code is read far more than it's written, and it's extremely easy to read this modular, explicit code. As you start to build large libraries of components you'll appreciate this explicitness and modularity, and with code reuse your lines of code will start to shrink :)
This is the 10th round-up already and React has come quite far since it was open sourced. Almost all new web projects at Khan Academy, Facebook, and Instagram are being developed using React. React has been deployed in a variety of contexts: a Chrome extension, a Windows 8 application, mobile websites, and desktop websites supporting Internet Explorer 8! Language-wise, React is not only being used within JavaScript but also CoffeeScript and ClojureScript.
The best part is that no drastic changes have been required to support all those use cases. Most of the efforts were targeted at polishing edge cases, performance improvements, and documentation.
## Khan Academy - Officially moving to React
[Joel Burget](http://joelburget.com/) announced at Hack Reactor that new front-end code at Khan Academy should be written in React!
> How did we get the rest of the team to adopt React? Using interns as an attack vector! Most full-time devs had already been working on their existing projects for a while and weren't looking to try something new at the time, but our class of summer interns was just arriving. For whatever reason, a lot of them decided to try React for their projects. Then mentors became exposed through code reviews or otherwise touching the new code. In this way React knowledge diffused to almost the whole team over the summer.
>
> Since the first React checkin on June 5, we've somehow managed to accumulate 23500 lines of jsx (React-flavored js) code. Which is terrifying in a way - that's a lot of code - but also really exciting that it was picked up so quickly.
>
> We held three meetings about how we should proceed with React. At the first two we decided to continue experimenting with React and deferred a final decision on whether to adopt it. At the third we adopted the policy that new code should be written in React.
>
> I'm excited that we were able to start nudging code quality forward. However, we still have a lot of work to do! One of the selling points of this transition is adopting a uniform frontend style. We're trying to upgrade all the code from (really old) pure jQuery and (regular old) Backbone views / Handlebars to shiny React. At the moment all we've done is introduce more fragmentation. We won't be gratuitously updating working code (if it ain't broke, don't fix it), but are seeking out parts of the codebase where we can shoot two birds with one stone by rewriting in React while fixing bugs or adding functionality.
>
> [Read the full article](http://joelburget.com/backbone-to-react/)
## React: Rethinking best practices
[Pete Hunt](http://www.petehunt.net/)'s talk at JSConf EU 2013 is now available in video.
[Stoyan Stefanov](http://www.phpied.com/)'s series of articles on React has two new entries on how to execute React on the server to generate the initial page load.
> This post is an initial hack to have React components render server-side in PHP.
>
> - Problem: Build web UIs
> - Solution: React
> - Problem: UI built in JS is anti-SEO (assuming search engines are still noscript) and bad for perceived performance (blank page till JS arrives)
> - Solution: [React page](https://github.com/facebook/react-page) to render the first view
> - Problem: Can't host node.js apps / I have tons of PHP code
> - Solution: Use PHP then!
>
> [**Read part 1 ...**](http://www.phpied.com/server-side-react-with-php/)
>
> [**Read part 2 ...**](http://www.phpied.com/server-side-react-with-php-part-2/)
Webkit has a [TodoMVC Benchmark](https://github.com/WebKit/webkit/tree/master/PerformanceTests/DoYouEvenBench) that compares different frameworks. They recently included React and here are the results (average of 10 runs in Chrome 30):
- **AngularJS:** 4043ms
- **AngularJSPerf:** 3227ms
- **BackboneJS:** 1874ms
- **EmberJS:** 6822ms
- **jQuery:** 14628ms
- **React:** 2864ms
- **VanillaJS:** 5567ms
[Try it yourself!](http://www.petehunt.net/react/tastejs/benchmark.html)
Please don't take those numbers too seriously, they only reflect one very specific use case and are testing code that wasn't written with performance in mind.
Even though React scores as one of the fastest frameworks in the benchmark, the React code is simple and idiomatic. The only performance tweak used is the following function:
```javascript
/**
* This is a completely optional performance enhancement that you can implement
* on any React component. If you were to delete this method the app would still
* work correctly (and still be very performant!), we just use it as an example
* of how little code it takes to get an order of magnitude performance improvement.
By default, React "re-renders" all the components when anything changes. This is usually fast enough that you don't need to care. However, you can provide a function that can tell whether there will be any change based on the previous and next states and props. If it is faster than re-rendering the component, then you get a performance improvement.
The fact that you can control when components are rendered is a very important characteristic of React as it gives you control over its performance. We are going to talk more about performance in the future, stay tuned.
## Guess the filter
[Connor McSheffrey](http://conr.me) implemented a small game using React. The goal is to guess which filter has been used to create the Instagram photo.
[Andrew Betts](http://trib.tv/), director of the [Financial Times Labs](http://labs.ft.com/), posted an article comparing [FruitMachine](https://github.com/ftlabs/fruitmachine) and React.
> Eerily similar, no? Maybe Facebook was inspired by Fruit Machine (after all, we got there first), but more likely, it just shows that this is a pretty decent way to solve the problem, and great minds think alike. We're graduating to a third phase in the evolution of web best practice - from intermingling of markup, style and behaviour, through a phase in which those concerns became ever more separated and encapsulated, and finally to a model where we can do that separation at a component level. Developments like Web Components show the direction the web community is moving, and frameworks like React and Fruit Machine are in fact not a lot more than polyfills for that promised behaviour to come.
>
> [Read the full article...](http://labs.ft.com/2013/10/client-side-layout-engines-react-vs-fruitmachine/)
Even though we weren't inspired by FruitMachine (React has been used in production since before FruitMachine was open sourced), it's great to see similar technologies emerging and becoming popular.
## React Brunch
[Matthew McCray](http://elucidata.net/) implemented [react-brunch](https://npmjs.org/package/react-brunch), a JSX compilation step for [Brunch](http://brunch.io/).
> Adds React support to brunch by automatically compiling `*.jsx` files.
>
> You can configure react-brunch to automatically insert a react header (`/** @jsx React.DOM */`) into all `*.jsx` files. Disabled by default.
>
> Install the plugin via npm with `npm install --save react-brunch`.
I'm going to start adding a tweet at the end of each round-up. We'll start with this one:
<blockquote class="twitter-tweet"><p>This weekend <a href="https://twitter.com/search?q=%23angular&src=hash">#angular</a> died for me. Meet new king <a href="https://twitter.com/search?q=%23reactjs&src=hash">#reactjs</a></p>— Eldar Djafarov ッ (@edjafarov) <a href="https://twitter.com/edjafarov/statuses/397033796710961152">November 3, 2013</a></blockquote>
This round-up is the proof that React has taken off from its Facebook's root: it features three in-depth presentations of React done by external people. This is awesome, keep them coming!
## Super VanJS 2013 Talk
[Steve Luscher](https://github.com/steveluscher) working at [LeanPub](https://leanpub.com/) made a 30 min talk at [Super VanJS](https://twitter.com/vanjs). He does a remarkable job at explaining why React is so fast with very exciting demos using the HTML5 Audio API.
[Connor McSheffrey](http://connormcsheffrey.com/) and [Cheng Lou](https://github.com/chenglou) added a new section to the documentation. It's a list of small tips that you will probably find useful while working on React. Since each article is very small and focused, we [encourage you to contribute](http://facebook.github.io/react/tips/introduction.html)!
- [Maximum Number of JSX Root Nodes](http://facebook.github.io/react/tips/maximum-number-of-jsx-root-nodes.html)
- [Shorthand for Specifying Pixel Values in style props](http://facebook.github.io/react/tips/style-props-value-px.html)
- [Type of the Children props](http://facebook.github.io/react/tips/children-props-type.html)
- [Value of null for Controlled Input](http://facebook.github.io/react/tips/controlled-input-null-value.html)
- [`componentWillReceiveProps` Not Triggered After Mounting](http://facebook.github.io/react/tips/componentWillReceiveProps-not-triggered-after-mounting.html)
- [Props in getInitialState Is an Anti-Pattern](http://facebook.github.io/react/tips/props-in-getInitialState-as-anti-pattern.html)
- [DOM Event Listeners in a Component](http://facebook.github.io/react/tips/dom-event-listeners.html)
- [Load Initial Data via AJAX](http://facebook.github.io/react/tips/initial-ajax.html)
- [False in JSX](http://facebook.github.io/react/tips/false-in-jsx.html)
## Intro to the React Framework
[Pavan Podila](http://blog.pixelingene.com/) wrote an in-depth introduction to React on TutsPlus. This is definitively worth reading.
> Within a component-tree, data should always flow down. A parent-component should set the props of a child-component to pass any data from the parent to the child. This is termed as the Owner-Owned pair. On the other hand user-events (mouse, keyboard, touches) will always bubble up from the child all the way to the root component, unless handled in between.
> [Read the full article ...](http://dev.tutsplus.com/tutorials/intro-to-the-react-framework--net-35660)
## 140-characters textarea
[Brian Kim](https://github.com/brainkim) wrote a small textarea component that gradually turns red as you reach the 140-characters limit. Because he only changes the background color, React is smart enough not to mess with the text selection.
<p data-height="178" data-theme-id="0" data-slug-hash="FECGb" data-user="brainkim" data-default-tab="result" class='codepen'>See the Pen <a href='http://codepen.io/brainkim/pen/FECGb'>FECGb</a> by Brian Kim (<a href='http://codepen.io/brainkim'>@brainkim</a>) on <a href='http://codepen.io'>CodePen</a></p>
[Eric Clemmons](http://ericclemmons.github.io/) is working on a "Modern, opinionated, full-stack starter kit for rapid, streamlined application development". The version 0.4.0 has just been released and has first-class support for React.
[Robert Zaremba](http://rz.scale-it.pl/) working on [AgFlow](http://www.agflow.com/) recently talked in Poland about React.
> In a nutshell, I presented why we chose React among other available options (ember.js, angular, backbone ...) in AgFlow, where I’m leading an application development.
>
> During the talk a wanted to highlight that React is not about implementing a Model, but a way to construct visible components with some state. React is simple. It is super simple, you can learn it in 1h. On the other hand what is model? Which functionality it should provide? React does one thing and does it the best (for me)!
>
> [Read the full article...](http://rz.scale-it.pl/2013/10/20/frontend_components_in_react.html)
[Todd Kennedy](http://tck.io/) working at Condé Nast wrote [JSXHint](https://github.com/CondeNast/JSXHint) and explains in a blog post his perspective on JSX.
> Lets start with the elephant in the room: JSX?
> Is this some sort of template language? Specifically no. This might have been the first big stumbling block. What looks like to be a templating language is actually an in-line DSL that gets transpiled directly into JavaScript by the JSX transpiler.
>
> Creating elements in memory is quick -- copying those elements into the DOM is where the slowness occurs. This is due to a variety of issues, most namely reflow/paint. Changing the items in the DOM causes the browser to re-paint the display, apply styles, etc. We want to keep those operations to an absolute minimum, especially if we're dealing with something that needs to update the DOM frequently.
>
> [Read the full article...](http://tck.io/posts/jsxhint_and_react.html)
## Photo Gallery
[Maykel Loomans](http://miekd.com/), designer at Instagram, wrote a gallery for photos he shot using React.
<div style="width: 320px;"><blockquote class="twitter-tweet"><p>I think this reversed gif of Steve Urkel best describes my changing emotions towards the React Lib <a href="http://t.co/JoX0XqSXX3">http://t.co/JoX0XqSXX3</a></p>— Ryan Seddon (@ryanseddon) <a href="https://twitter.com/ryanseddon/statuses/398572848802852864">November 7, 2013</a></blockquote></div>
Today we're releasing an update to address a potential XSS vulnerability that can arise when using user data as a `key`. Typically "safe" data is used for a `key`, for example, an id from your database, or a unique hash. However there are cases where it may be reasonable to use user generated content. A carefully crafted piece of content could result in arbitrary JS execution. While we make a very concerted effort to ensure all text is escaped before inserting it into the DOM, we missed one case. Immediately following the discovery of this vulnerability, we performed an audit to ensure we this was the only such vulnerability.
This only affects v0.5.x and v0.4.x. Versions in the 0.3.x family are unaffected.
Updated versions are available for immediate download via npm, bower, and on our [download page][download].
We take security very seriously at Facebook. For most of our products, users don't need to know that a security issue has been fixed. But with libraries like React, we need to make sure developers using React have access to fixes to keep their users safe.
While we've encouraged responsible disclosure as part of [Facebook's whitehat bounty program][bounty] since we launched, we don't have a good process for notifying our users. Hopefully we don't need to use it, but moving forward we'll set up a little bit more process to ensure the safety of our users. Ember.js has [an excellent policy][ember] which we may use as our model.
You can learn more about the vulnerability discussed here: [CVE-2013-7035][cve].
It's become increasingly obvious since our launch in May that people want to use React on the server. With the server-side rendering abilities, that's a perfect fit. However using the same copy of React on the server and then packaging it up for the client is surprisingly a harder problem. People have been using our `react-tools` module which includes React, but when browserifying that ends up packaging all of `esprima` and some other dependencies that aren't needed on the client. So we wanted to make this whole experience better.
We talked with [Jeff Barczewski][jeff] who was the owner of the `react` module on npm. He was kind enough to transition ownership to us and release his package under a different name: `autoflow`. I encourage you to [check it out][autoflow] if you're writing a lot of asynchronous code. In order to not break all of `react`'s current users of 0.7.x, we decided to bump our version to 0.8 and skip the issue entirely. We're also including a warning if you use our `react` module like you would use the previous package.
In order to make the transition to 0.8 for our current users as painless as possible, we decided to make 0.8 primarily a bug fix release on top of 0.5. No public APIs were changed (even if they were already marked as deprecated). We haven't added any of the new features we have in master, though we did take the opportunity to pull in some improvements to internals.
We hope that by releasing `react` on npm, we will enable a new set of uses that have been otherwise difficult. All feedback is welcome!
## Changelog
### React
* Added support for more attributes:
*`rows` & `cols` for `<textarea>`
*`defer` & `async` for `<script>`
*`loop` for `<audio>` & `<video>`
*`autoCorrect` for form fields (a non-standard attribute only supported by mobile WebKit)
* Improved error messages
* Fixed Selection events in IE11
* Added `onContextMenu` events
### React with Addons
* Fixed bugs with TransitionGroup when children were undefined
* Added support for `onTransition`
### react-tools
* Upgraded `jstransform` and `esprima-fb`
### JSXTransformer
* Added support for use in IE8
* Upgraded browserify, which reduced file size by ~65KB (16KB gzipped)
React got featured on the front-page of Hacker News thanks to the Om library. If you try it out for the first time, take a look at the [docs](/react/docs/getting-started.html) and do not hesitate to ask questions on the [Google Group](http://groups.google.com/group/reactjs), [IRC](irc://chat.freenode.net/reactjs) or [Stack Overflow](http://stackoverflow.com/questions/tagged/reactjs). We are trying our best to help you out!
## The Future of Javascript MVC
[David Nolen](http://swannodette.github.io/) announced Om, a thin wrapper on-top of React in ClojureScript. It stands out by only using immutable data structures. This unlocks the ability to write a very efficient [shouldComponentUpdate](http://facebook.github.io/react/docs/component-specs.html#updating-shouldcomponentupdate) and get huge performance improvements on some tasks.
> We've known this for some time over here in the ClojureScript corner of the world - all of our collections are immutable and modeled directly on the original Clojure versions written in Java. Modern JavaScript engines have now been tuned to the point that it's no longer uncommon to see collection performance within 2.5X of the Java Virtual Machine.
>
> Wait, wait, wait. What does the performance of persistent data structures have to do with the future of JavaScript MVCs?
> [Read the full article...](http://swannodette.github.io/2013/12/17/the-future-of-javascript-mvcs/)
## Scroll Position with React
Managing the scroll position when new content is inserted is usually very tricky to get right. [Vjeux](http://blog.vjeux.com/) discovered that [componentWillUpdate](http://facebook.github.io/react/docs/component-specs.html#updating-componentwillupdate) and [componentDidUpdate](http://facebook.github.io/react/docs/component-specs.html#updating-componentdidupdate) were triggered exactly at the right time to manage the scroll position.
> We can check the scroll position before the component has updated with componentWillUpdate and scroll if necessary at componentDidUpdate
> [Check out the blog article...](http://blog.vjeux.com/2013/javascript/scroll-position-with-react.html)
## Lights Out
React declarative approach is well suited to write games. [Cheng Lou](https://github.com/chenglou) wrote the famous Lights Out game in React. It's a good example of use of [TransitionGroup](http://facebook.github.io/react/docs/animation.html) to implement animations.
[Try it out!](http://chenglou.github.io/react-lights-out/)
## Reactive Table Bookmarklet
[Stoyan Stefanov](http://www.phpied.com/) wrote a bookmarklet to process tables on the internet. It adds a little "pop" button that expands to a full-screen view with sorting, editing and export to csv and json.
[Check out the blog post...](http://www.phpied.com/reactivetable-bookmarklet/)
## MontageJS Tutorial in React
[Ross Allen](https://twitter.com/ssorallen) implemented [MontageJS](http://montagejs.org/)'s [Reddit tutorial](http://montagejs.org/docs/tutorial-reddit-client-with-montagejs.html) in React. This is a good opportunity to compare the philosophies of the two libraries.
[View the source on JSFiddle...](http://jsfiddle.net/ssorallen/fEsYt/)
## Writing Good React Components
[William Högman Rudenmalm](http://blog.whn.se/) wrote an article on how to write good React components. This is full of good advice.
> The idea of dividing software into smaller parts or components is hardly new - It is the essance of good software. The same principles that apply to software in general apply to building React components. That doesn’t mean that writing good React components is just about applying general rules.
>
> The web offers a unique set of challenges, which React offers interesting solutions to. First and foremost among these solutions is the what is called the Mock DOM. Rather than having user code interface with the DOM in a direct fashion, as is the case with most DOM manipulation libraries.
>
> You build a model of how you want the DOM end up like. React then inserts this model into the DOM. This is very useful for updates because React simply compares the model or mock DOM against the actual DOM, and then only updates based on the difference between the two states.
>
> [Read the full article ...](http://blog.whn.se/post/69621609605/writing-good-react-components)
## Hoodie React TodoMVC
[Sven Lito](http://svenlito.com/) integrated the React TodoMVC example within an [Hoodie](http://hood.ie/) web app environment. This should let you get started using Hoodie and React.
```
hoodie new todomvc -t "hoodiehq/hoodie-react-todomvc"
```
[Check out on GitHub...](https://github.com/hoodiehq/hoodie-react-todomvc)
## JSX Compiler
Ever wanted to have a quick way to see what a JSX tag would be converted to? [Tim Yung](http://www.yungsters.com/) made a page for it.
[Try it out!](http://facebook.github.io/react/jsx-compiler.html)
## Random Tweet
<center><blockquote class="twitter-tweet" lang="en"><p>.<a href="https://twitter.com/jordwalke">@jordwalke</a> lays down some truth <a href="http://t.co/AXAn0UlUe3">http://t.co/AXAn0UlUe3</a>, optimizing your JS application shouldn't force you to rewrite so much code <a href="https://twitter.com/search?q=%23reactjs&src=hash">#reactjs</a></p>— David Nolen (@swannodette) <a href="https://twitter.com/swannodette/statuses/413780079249215488">December 19, 2013</a></blockquote></center>
Happy holidays! This blog post is a little-late Christmas present for all the React users. Hopefully it will inspire you to write awesome web apps in 2014!
## React Touch
[Pete Hunt](http://www.petehunt.net/) wrote three demos showing that React can be used to run 60fps native-like experiences on mobile web. A frosted glass effect, an image gallery with 3d animations and an infinite scroll view.
[Try out the demos!](http://petehunt.github.io/react-touch/)
## Introduction to React
[Stoyan Stefanov](http://www.phpied.com/) talked at Joe Dev On Tech about React. He goes over all the features of the library and ends with a concrete example.
JSX is often compared to the now defunct E4X, [Vjeux](http://blog.vjeux.com/) went over all the E4X features and explained how JSX is different and hopefully doesn't repeat the same mistakes.
> E4X (ECMAScript for XML) is a Javascript syntax extension and a runtime to manipulate XML. It was promoted by Mozilla but failed to become mainstream and is now deprecated. JSX was inspired by E4X. In this article, I'm going to go over all the features of E4X and explain the design decisions behind JSX.
>
> **Historical Context**
>
> E4X has been created in 2002 by John Schneider. This was the golden age of XML where it was being used for everything: data, configuration files, code, interfaces (DOM) ... E4X was first implemented inside of Rhino, a Javascript implementation from Mozilla written in Java.
[Geert Pasteels](http://enome.be/nl) made a small experiment with Socket.io. He wrote a very small mixin that synchronizes React state with the server. Just include this mixin to your React component and it is now live!
[Check it out on GitHub...](https://github.com/Enome/react.io)
## cssobjectify
[Andrey Popp](http://andreypopp.com/) implemented a source transform that takes a CSS file and converts it to JSON. This integrates pretty nicely with React.
[Check it out on GitHub...](https://github.com/andreypopp/cssobjectify)
## ngReact
[David Chang](http://davidandsuzi.com/) working at [HasOffer](http://www.hasoffers.com/) wanted to speed up his Angular app and replaced Angular primitives by React at different layers. When using React naively it is 67% faster, but when combining it with angular's transclusion it is 450% slower.
> Rendering this takes 803ms for 10 iterations, hovering around 35 and 55ms for each data reload (that's 67% faster). You'll notice that the first load takes a little longer than successive loads, and the second load REALLY struggles - here, it's 433ms, which is more than half of the total time!
> [Read the full article...](http://davidandsuzi.com/ngreact-react-components-in-angular/)
## vim-jsx
[Max Wang](https://github.com/mxw) made a vim syntax highlighting and indentation plugin for vim.
> Syntax highlighting and indenting for JSX. JSX is a JavaScript syntax transformer which translates inline XML document fragments into JavaScript objects. It was developed by Facebook alongside React.
>
> This bundle requires pangloss's [vim-javascript](https://github.com/pangloss/vim-javascript) syntax highlighting.
>
> Vim support for inline XML in JS is remarkably similar to the same for PHP.
>
> [View on GitHub...](https://github.com/mxw/vim-jsx)
## Random Tweet
<center><blockquote class="twitter-tweet" lang="en"><p>I may be starting to get annoying with this, but ReactJS is really exciting. I truly feel the virtual DOM is a game changer.</p>— Eric Florenzano (@ericflo) <a href="https://twitter.com/ericflo/statuses/413842834974732288">December 20, 2013</a></blockquote></center>
With the new year, we thought you'd enjoy some new tools for debugging React code. Today we're releasing the [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi), an extension to the Chrome Developer Tools. [Download them from the Chrome Web Store](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi).
You will get a new tab titled "React" in your Chrome DevTools. This tab shows you a list of the root React Components that are rendered on the page as well as the subcomponents that each root renders.
Selecting a Component in this tab allows you to view and edit its props and state in the panel on the right. In the breadcrumbs at the bottom, you can inspect the selected Component, the Component that created it, the Component that created that one, and so on.
When you inspect a DOM element using the regular Elements tab, you can switch over to the React tab and the corresponding Component will be automatically selected. The Component will also be automatically selected if you have a breakpoint within its render phase. This allows you to step through the render tree and see how one Component affects another one.
We hope these tools will help your team better understand your component hierarchy and track down bugs. We're very excited about this initial launch and appreciate any feedback you may have. As always, we also accept [pull requests on GitHub](https://github.com/facebook/react-devtools).
The theme of this first round-up of 2014 is integration. I've tried to assemble a list of articles and projects that use React in various environments.
## React Baseline
React is only one-piece of your web application stack. [Mark Lussier](https://github.com/intabulas) shared his baseline stack that uses React along with Grunt, Browserify, Bower, Zepto, Director and Sass. This should help you get started using React for a new project.
> As I do more projects with ReactJS I started to extract a baseline to use when starting new projects. This is very opinionated and I change my opinion from time to time. This is by no ways perfect and in your opinion most likely wrong :).. which is why I love github
>
> I encourage you to fork, and make it right and submit a pull request!
>
> My current opinion is using tools like Grunt, Browserify, Bower and mutiple grunt plugins to get the job done. I also opted for Zepto over jQuery and the Flatiron Project's Director when I need a router. Oh and for the last little bit of tech that makes you mad, I am in the SASS camp when it comes to stylesheets
>
> [Check it out on GitHub...](https://github.com/intabulas/reactjs-baseline)
## Animal Sounds
[Josh Duck](http://joshduck.com/) used React in order to build a Windows 8 tablet app. This is a good example of a touch app written in React.
[Download the app...](http://apps.microsoft.com/windows/en-us/app/baby-play-animal-sounds/9280825c-2ed9-41c0-ba38-aa9a5b890bb9)
## React Rails Tutorial
[Selem Delul](http://selem.im) bundled the [React Tutorial](http://facebook.github.io/react/docs/tutorial.html) into a rails app. This is a good example on how to get started with a rails project.
> Then visit http://localhost:3000/app to see the React application that is explained in the React Tutorial. Try opening multiple tabs!
>
> [View on GitHub...](https://github.com/necrodome/react-rails-tutorial)
## Mixing with Backbone
[Eldar Djafarov](http://eldar.djafarov.com/) implemented a mixin to link Backbone models to React state and a small abstraction to write two-way binding on-top.
[Check out the blog post...](http://eldar.djafarov.com/2013/11/reactjs-mixing-with-backbone/)
## React Infinite Scroll
[Guillaume Rivals](https://twitter.com/guillaumervls) implemented an InfiniteScroll component. This is a good example of a React component that has a simple yet powerful API.
React is often compared with Angular. [Pete Hunt](http://skulbuny.com/2013/10/31/react-vs-angular/) wrote an opinionated post on the subject.
> First of all I think it’s important to evaluate technologies on objective rather than subjective features. “It feels nicer” or “it’s cleaner” aren’t valid reasons: performance, modularity, community size and ease of testing / integration with other tools are.
>
> I’ve done a lot of work benchmarking, building apps, and reading the code of Angular to try to come up with a reasonable comparison between their ways of doing things.
>
> [Read the full post...](http://skulbuny.com/2013/10/31/react-vs-angular/)
## Random Tweet
<div><blockquote class="twitter-tweet" lang="en"><p>Really intrigued by React.js. I've looked at all JS frameworks, and excepting <a href="https://twitter.com/serenadejs">@serenadejs</a> this is the first one which makes sense to me.</p>— Jonas Nicklas (@jonicklas) <a href="https://twitter.com/jonicklas/statuses/412640708755869696">December 16, 2013</a></blockquote></div>
Interest in React seems to have surged ever since David Nolen ([@swannodette](https://twitter.com/swannodette))'s introduction of [Om](https://github.com/swannodette/om) in his post ["The Future of Javascript MVC Frameworks"](http://swannodette.github.io/2013/12/17/the-future-of-javascript-mvcs/).
In this React Community Round-up, we are taking a closer look at React from a functional programming perspective.
## "React: Another Level of Indirection"
To start things off, Eric Normand ([@ericnormand](https://twitter.com/ericnormand)) of [LispCast](http://lispcast.com) makes the case for [React from a general functional programming standpoint](http://www.lispcast.com/react-another-level-of-indirection) and explains how React's "Virtual DOM provides the last piece of the Web Frontend Puzzle for ClojureScript".
> The Virtual DOM is an indirection mechanism that solves the difficult problem of DOM programming: how to deal with incremental changes to a stateful tree structure. By abstracting away the statefulness, the Virtual DOM turns the real DOM into an immediate mode GUI, which is perfect for functional programming.
>
> [Read the full post...](http://www.lispcast.com/react-another-level-of-indirection)
## Reagent: Minimalistic React for ClojureScript
Dan Holmsand ([@holmsand](https://twitter.com/holmsand)) created [Reagent](http://holmsand.github.io/reagent/), a simplistic ClojureScript API to React.
> It allows you to define efficient React components using nothing but plain ClojureScript functions and data, that describe your UI using a Hiccup-like syntax.
>
> The goal of Reagent is to make it possible to define arbitrarily complex UIs using just a couple of basic concepts, and to be fast enough by default that you rarely have to care about performance.
>
> [Check it out on Github...](http://holmsand.github.io/reagent/)
## Functional DOM programming
React's one-way data-binding naturally lends itself to a functional programming approach. Facebook's Pete Hunt ([@floydophone](https://twitter.com/floydophone)) explores how one would go about [writing web apps in a functional manner](https://medium.com/p/67d81637d43). Spoiler alert:
> This is React. It’s not about templates, or data binding, or DOM manipulation. It’s about using functional programming with a virtual DOM representation to build ambitious, high-performance apps with JavaScript.
>
> [Read the full post...](https://medium.com/p/67d81637d43)
Pete also explains this in detail at his #MeteorDevShop talk (about 30 Minutes):
[Creighton Kirkendall](https://github.com/ckirkendall) created [Kioo](https://github.com/ckirkendall/kioo), which adds Enlive-style templating to React. HTML templates are separated from the application logic. Kioo comes with separate examples for both Om and Reagent.
In an interview with David Nolen, Tom Coupland ([@tcoupland](https://twitter.com/tcoupland)) of InfoQ provides a nice summary of recent developments around Om ("[Om: Enhancing Facebook's React with Immutability](http://www.infoq.com/news/2014/01/om-react)").
> David [Nolen]: I think people are starting to see the limitations of just JavaScript and jQuery and even more structured solutions like Backbone, Angular, Ember, etc. React is a fresh approach to the DOM problem that seems obvious in hindsight.
>
> [Read the full interview...](http://www.infoq.com/news/2014/01/om-react)
### A slice of React, ClojureScript and Om
Fredrik Dyrkell ([@lexicallyscoped](https://twitter.com/lexicallyscoped)) rewrote part of the [React tutorial in both ClojureScript and Om](http://www.lexicallyscoped.com/2013/12/25/slice-of-reactjs-and-cljs.html), along with short, helpful explanations.
> React has sparked a lot of interest in the Clojure community lately [...]. At the very core, React lets you build up your DOM representation in a functional fashion by composing pure functions and you have a simple building block for everything: React components.
>
> [Read the full post...](http://www.lexicallyscoped.com/2013/12/25/slice-of-reactjs-and-cljs.html)
In a separate post, Dyrkell breaks down [how to build a binary clock component](http://www.lexicallyscoped.com/2014/01/23/ClojureScript-react-om-binary-clock.html) in Om.
David Nolen shows how to leverage immutable data structures to [add global undo](http://swannodette.github.io/2013/12/31/time-travel/) functionality to an app – using just 13 lines of ClojureScript.
### A Step-by-Step Om Walkthrough
[Josh Lehman](http://www.joshlehman.me) took the time to create an extensive [step-by-step walkthrough](http://www.joshlehman.me/rewriting-the-react-tutorial-in-om/) of the React tutorial in Om. The well-documented source is on [github](https://github.com/jalehman/omtut-starter).
### Omkara
[brendanyounger](https://github.com/brendanyounger) created [omkara](https://github.com/brendanyounger/omkara), a starting point for ClojureScript web apps based on Om/React. It aims to take advantage of server-side rendering and comes with a few tips on getting started with Om/React projects.
### Om Experience Report
Adam Solove ([@asolove](https://twitter.com/asolove/)) [dives a little deeper into Om, React and ClojureScript](http://adamsolove.com/js/clojure/2014/01/06/om-experience-report.html). He shares some helpful tips he gathered while building his [CartoCrayon](https://github.com/asolove/carto-crayon) prototype.
## Not-so-random Tweet
<div><blockquote class="twitter-tweet" lang="en"><p>[@swannodette](https://twitter.com/swannodette) No thank you! It's honestly a bit weird because Om is exactly what I didn't know I wanted for doing functional UI work.</p>— Adam Solove (@asolove) <a href="https://twitter.com/asolove/status/420294067637858304">January 6, 2014</a></blockquote></div>
There have been many posts recently covering the <i>why</i> and <i>how</i> of React. This week's community round-up includes a collection of recent articles to help you get started with React, along with a few posts that explain some of the inner workings.
## React in a nutshell
Got five minutes to pitch React to your coworkers? John Lynch ([@johnrlynch](https://twitter.com/johnrlynch)) put together [this excellent and refreshing slideshow](http://slid.es/johnlynch/reactjs):
React core team member Christopher Chedeau ([@vjeux](https://twitter.com/vjeux)) explores the innards of React's tree diffing algorithm in this [extensive and well-illustrated post](http://calendar.perfplanet.com/2013/diff/). <figure>[](http://calendar.perfplanet.com/2013/diff/)</figure>
While we're talking about tree diffing: Matt Esch ([@MatthewEsch](https://twitter.com/MatthewEsch)) created [this project](https://github.com/Matt-Esch/virtual-dom), which aims to implement the virtual DOM and a corresponding diff algorithm as separate modules.
## Many, many new introductions to React!
James Padosley wrote a short post on the basics (and merits) of React: [What is React?](http://james.padolsey.com/javascript/what-is-react/)
> What I like most about React is that it doesn't impose heady design patterns and data-modelling abstractions on me. [...] Its opinions are so minimal and its abstractions so focused on the problem of the DOM, that you can merrily slap your design choices atop.
> [Read the full post...](http://james.padolsey.com/javascript/what-is-react/)
Taylor Lapeyre ([@taylorlapeyre](https://twitter.com/taylorlapeyre)) wrote another nice [introduction to React](http://words.taylorlapeyre.me/an-introduction-to-react).
> React expects you to do the work of getting and pushing data from the server. This makes it very easy to implement React as a front end solution, since it simply expects you to hand it data. React does all the other work.
> [Read the full post...](http://words.taylorlapeyre.me/an-introduction-to-react)
[This "Deep explanation for newbies"](http://www.webdesignporto.com/react-js-in-pure-javascript-facebook-library/?utm_source=echojs&utm_medium=post&utm_campaign=echojs) by [@ProJavaScript](https://twitter.com/ProJavaScript) explains how to get started building a React game without using the optional JSX syntax.
### React around the world
It's great to see the React community expand internationally. [This site](http://habrahabr.ru/post/189230/) features a React introduction in Russian.
### React tutorial series
[Christopher Pitt](https://medium.com/@followchrisp) explains [React Components](https://medium.com/react-tutorials/828c397e3dc8) and [React Properties](https://medium.com/react-tutorials/ef11cd55caa0). The former includes a nice introduction to using JSX, while the latter focuses on adding interactivity and linking multiple components together. Also check out the [other posts in his React Tutorial series](https://medium.com/react-tutorials), e.g. on using [React + Backbone Model](https://medium.com/react-tutorials/8aaec65a546c) and [React + Backbone Router](https://medium.com/react-tutorials/c00be0cf1592).
### Beginner tutorial: Implementing the board game Go
[Chris LaRose](http://cjlarose.com/) walks through the steps of creating a Go app in React, showing how to separate application logic from the rendered components. Check out his [tutorial](http://cjlarose.com/2014/01/09/react-board-game-tutorial.html) or go straight to the [code](https://github.com/cjlarose/react-go).
### Egghead.io video tutorials
Joe Maddalone ([@joemaddalone](https://twitter.com/joemaddalone)) of [egghead.io](https://egghead.io/) created a series of React video tutorials, such as [this](http://www.youtube.com/watch?v=rFvZydtmsxM&feature=youtu.be&a) introduction to React Components. [[part 1](http://www.youtube.com/watch?v=rFvZydtmsxM&feature=youtu.be&a)], [[part 2](http://www.youtube.com/watch?v=5yvFLrt7N8M)]
### "React: Finally, a great server/client web stack"
Eric Florenzano ([@ericflo](https://twitter.com/ericflo)) sheds some light on what makes React perfect for server rendering:
> [...] the ideal solution would fully render the markup on the server, deliver it to the client so that it can be shown to the user instantly. Then it would asynchronously load some Javascript that would attach to the rendered markup, and invisibly promote the page into a full app that can render its own markup. [...]
> What I've discovered is that enough of the pieces have come together, that this futuristic-sounding web environment is actually surprisingly easy to do now with React.js.
> [Read the full post...](http://eflorenzano.com/blog/2014/01/23/react-finally-server-client/)
## Building a complex React component
[Matt Harrison](http://matt-harrison.com/) walks through the process of [creating an SVG-based Resistance Calculator](http://matt-harrison.com/building-a-complex-web-component-with-facebooks-react-library/) using React. <figure>[](http://matt-harrison.com/building-a-complex-web-component-with-facebooks-react-library/)</figure>
## Random Tweets
<div><blockquote class="twitter-tweet" lang="en"><p>[#reactjs](https://twitter.com/search?q=%23reactjs&src=hash) has very simple API, but it's amazing how much work has been done under the hood to make it blazing fast.</p>— Anton Astashov (@anton_astashov) <a href="https://twitter.com/anton_astashov/status/417556491646693378">December 30, 2013</a></blockquote></div>
<div><blockquote class="twitter-tweet" lang="en"><p>[#reactjs]((https://twitter.com/search?q=%23reactjs&src=hash) makes refactoring your HTML as easy & natural as refactoring your javascript [@react_js](https://twitter.com/react_js)</p>— Jared Forsyth (@jaredforsyth) <a href="https://twitter.com/jaredforsyth/status/420304083010854912">January 6, 2014</a></blockquote></div>
<div><blockquote class="twitter-tweet" lang="en"><p>Played with react.js for an hour, so many things suddenly became stupidly simple.</p>— andrewingram (@andrewingram) <a href="https://twitter.com/andrewingram/status/422810480701620225">January 13, 2014</a></blockquote></div>
We're almost ready to release React v0.9! We're posting a release candidate so that you can test your apps on it; we'd much prefer to find show-stopping bugs now rather than after we release.
The release candidate is available for download from the CDN:
* **React**
Dev build with warnings: <http://fb.me/react-0.9.0-rc1.js>
Minified build for production: <http://fb.me/react-0.9.0-rc1.min.js>
***React with Add-Ons**
Dev build with warnings: <http://fb.me/react-with-addons-0.9.0-rc1.js>
Minified build for production: <http://fb.me/react-with-addons-0.9.0-rc1.min.js>
***In-Browser JSX transformer**
<http://fb.me/JSXTransformer-0.9.0-rc1.js>
We've also published version `0.9.0-rc1` of the `react` and `react-tools` packages on npm and the `react` package on bower.
Please try these builds out and [file an issue on GitHub](https://github.com/facebook/react/issues/new) if you see anything awry.
## Upgrade Notes
In addition to the changes to React core listed below, we've made a small change to the way JSX interprets whitespace to make things more consistent. With this release, space between two components on the same line will be preserved, while a newline separating a text node from a tag will be eliminated in the output. Consider the code:
```html
<div>
Monkeys:
{listOfMonkeys} {submitButton}
</div>
```
In v0.8 and below, it was transformed to the following:
```javascript
React.DOM.div(null,
" Monkeys: ",
listOfMonkeys,submitButton
)
```
In v0.9, it will be transformed to this JS instead:
```javascript{2,3}
React.DOM.div(null,
"Monkeys:",
listOfMonkeys, " ", submitButton
)
```
We believe this new behavior is more helpful and elimates cases where unwanted whitespace was previously added.
In cases where you want to preserve the space adjacent to a newline, you can write a JS string like `{"Monkeys: "}` in your JSX source. We've included a script to do an automated codemod of your JSX source tree that preserves the old whitespace behavior by adding and removing spaces appropriately. You can [install jsx\_whitespace\_transformer from npm](https://github.com/facebook/react/blob/master/npm-jsx_whitespace_transformer/README.md) and run it over your source tree to modify files in place. The transformed JSX files will preserve your code's existing whitespace behavior.
## Changelog
### React Core
#### Breaking Changes
- The lifecycle methods `componentDidMount` and `componentDidUpdate` no longer receive the root node as a parameter; use `this.getDOMNode()` instead
- Whenever a prop is equal to `undefined`, the default value returned by `getDefaultProps` will now be used instead
- `React.unmountAndReleaseReactRootNode` was previously deprecated and has now been removed
- `React.renderComponentToString` is now synchronous and returns the generated HTML string
- Full-page rendering (that is, rendering the `<html>` tag using React) is now supported only when starting with server-rendered markup
- On mouse wheel events, `deltaY` is no longer negated
- When prop types validation fails, a warning is logged instead of an error thrown (with the production build of React, the type checks are now skipped for performance)
- On `input`, `select`, and `textarea` elements, `.getValue()` is no longer supported; use `.getDOMNode().value` instead
- `this.context` on components is now reserved for internal use by React
#### New Features
- React now never rethrows errors, so stack traces are more accurate and Chrome's purple break-on-error stop sign now works properly
- Added a new tool for profiling React components and identifying places where defining `shouldComponentUpdate` can give performance improvements
- Added support for SVG tags `defs`, `linearGradient`, `polygon`, `radialGradient`, `stop`
- Added support for more attributes:
- `noValidate` and `formNoValidate` for forms
- `property` for Open Graph `<meta>` tags
- `sandbox`, `seamless`, and `srcDoc` for `<iframe>` tags
- `scope` for screen readers
- `span` for `<colgroup>` tags
- Added support for defining `propTypes` in mixins
- Added `any`, `arrayOf`, `component`, `oneOfType`, `renderable`, `shape` to `React.PropTypes`
- Added support for `statics` on component spec for static component methods
- On all events, `.currentTarget` is now properly set
- On keyboard events, `.key` is now polyfilled in all browsers for special (non-printable) keys
- On clipboard events, `.clipboardData` is now polyfilled in IE
- On drag events, `.dataTransfer` is now present
- Added support for `onMouseOver` and `onMouseOut` in addition to the existing `onMouseEnter` and `onMouseLeave` events
- Added support for `onLoad` and `onError` on `<img>` elements
- Added support for `onReset` on `<form>` elements
- The `autoFocus` attribute is now polyfilled consistently on `input`, `select`, and `textarea`
#### Bug Fixes
- React no longer adds an `__owner__` property to each component's `props` object; passed-in props are now never mutated
- When nesting top-level components (e.g., calling `React.renderComponent` within `componentDidMount`), events now properly bubble to the parent component
- Fixed a case where nesting top-level components would throw an error when updating
- Passing an invalid or misspelled propTypes type now throws an error
- On mouse enter/leave events, `.target`, `.relatedTarget`, and `.type` are now set properly
- On composition events, `.data` is now properly normalized in IE9 and IE10
- CSS property values no longer have `px` appended for the unitless properties `columnCount`, `flex`, `flexGrow`, `flexShrink`, `lineClamp`, `order`, `widows`
- Fixed a memory leak when unmounting children with a `componentWillUnmount` handler
- Fixed a memory leak when `renderComponentToString` would store event handlers
- Fixed an error that could be thrown when removing form elements during a click handler
- `key` values containing `.` are now supported
- Shortened `data-reactid` values for performance
- Components now always remount when the `key` property changes
- Event handlers are attached to `document` only when necessary, improving performance in some cases
- Events no longer use `.returnValue` in modern browsers, eliminating a warning in Chrome
- `scrollLeft` and `scrollTop` are no longer accessed on document.body, eliminating a warning in Chrome
- General performance fixes, memory optimizations, improvements to warnings and error messages
### React with Addons
- `React.addons.TransitionGroup` was renamed to `React.addons.CSSTransitionGroup`
- `React.addons.TransitionGroup` was added as a more general animation wrapper
- `React.addons.cloneWithProps` was added for cloning components and modifying their props
- Bug fix for adding back nodes during an exit transition for CSSTransitionGroup
- Bug fix for changing `transitionLeave` in CSSTransitionGroup
- Performance optimizations for CSSTransitionGroup
- On checkbox `<input>` elements, `checkedLink` is now supported for two-way binding
### JSX Compiler and react-tools Package
- Whitespace normalization has changed; now space between two tags on the same line will be preserved, while newlines between two tags will be removed
- The `react-tools` npm package no longer includes the React core libraries; use the `react` package instead.
- `displayName` is now added in more cases, improving error messages and names in the React Dev Tools
- Fixed an issue where an invalid token error was thrown after a JSX closing tag
- `JSXTransformer` now uses source maps automatically in modern browsers
- `JSXTransformer` error messages now include the filename and problematic line contents when a file fails to parse
I'm excited to announce that today we're releasing React v0.9, which incorporates many bug fixes and several new features since the last release. This release contains almost four months of work, including over 800 commits from over 70 committers!
Thanks to everyone who tested the release candidate; we were able to find and fix an error in the event handling code, we upgraded envify to make running browserify on React faster, and we added support for five new attributes.
As always, the release is available for download from the CDN:
* **React**
Dev build with warnings: <http://fb.me/react-0.9.0.js>
Minified build for production: <http://fb.me/react-0.9.0.min.js>
***React with Add-Ons**
Dev build with warnings: <http://fb.me/react-with-addons-0.9.0.js>
Minified build for production: <http://fb.me/react-with-addons-0.9.0.min.js>
***In-Browser JSX Transformer**
<http://fb.me/JSXTransformer-0.9.0.js>
We've also published version `0.9.0` of the `react` and `react-tools` packages on npm and the `react` package on bower.
## What’s New?
This version includes better support for normalizing event properties across all supported browsers so that you need to worry even less about cross-browser differences. We've also made many improvements to error messages and have refactored the core to never rethrow errors, so stack traces are more accurate and Chrome's purple break-on-error stop sign now works properly.
We've also added to the add-ons build [React.addons.TestUtils](/react/docs/test-utils.html), a set of new utilities to help you write unit tests for React components. You can now simulate events on your components, and several helpers are provided to help make assertions about the rendered DOM tree.
We've also made several other improvements and a few breaking changes; the full changelog is provided below.
## JSX Whitespace
In addition to the changes to React core listed below, we've made a small change to the way JSX interprets whitespace to make things more consistent. With this release, space between two components on the same line will be preserved, while a newline separating a text node from a tag will be eliminated in the output. Consider the code:
```html
<div>
Monkeys:
{listOfMonkeys} {submitButton}
</div>
```
In v0.8 and below, it was transformed to the following:
```javascript
React.DOM.div(null,
" Monkeys: ",
listOfMonkeys,submitButton
)
```
In v0.9, it will be transformed to this JS instead:
```javascript{2,3}
React.DOM.div(null,
"Monkeys:",
listOfMonkeys, " ", submitButton
)
```
We believe this new behavior is more helpful and elimates cases where unwanted whitespace was previously added.
In cases where you want to preserve the space adjacent to a newline, you can write `{'Monkeys: '}` or `Monkeys:{' '}` in your JSX source. We've included a script to do an automated codemod of your JSX source tree that preserves the old whitespace behavior by adding and removing spaces appropriately. You can [install jsx\_whitespace\_transformer from npm](https://github.com/facebook/react/blob/master/npm-jsx_whitespace_transformer/README.md) and run it over your source tree to modify files in place. The transformed JSX files will preserve your code's existing whitespace behavior.
## Changelog
### React Core
#### Breaking Changes
- The lifecycle methods `componentDidMount` and `componentDidUpdate` no longer receive the root node as a parameter; use `this.getDOMNode()` instead
- Whenever a prop is equal to `undefined`, the default value returned by `getDefaultProps` will now be used instead
- `React.unmountAndReleaseReactRootNode` was previously deprecated and has now been removed
- `React.renderComponentToString` is now synchronous and returns the generated HTML string
- Full-page rendering (that is, rendering the `<html>` tag using React) is now supported only when starting with server-rendered markup
- On mouse wheel events, `deltaY` is no longer negated
- When prop types validation fails, a warning is logged instead of an error thrown (with the production build of React, type checks are now skipped for performance)
- On `input`, `select`, and `textarea` elements, `.getValue()` is no longer supported; use `.getDOMNode().value` instead
- `this.context` on components is now reserved for internal use by React
#### New Features
- React now never rethrows errors, so stack traces are more accurate and Chrome's purple break-on-error stop sign now works properly
- Added support for SVG tags `defs`, `linearGradient`, `polygon`, `radialGradient`, `stop`
- Added support for more attributes:
- `crossOrigin` for CORS requests
- `download` and `hrefLang` for `<a>` tags
- `mediaGroup` and `muted` for `<audio>` and `<video>` tags
- `noValidate` and `formNoValidate` for forms
- `property` for Open Graph `<meta>` tags
- `sandbox`, `seamless`, and `srcDoc` for `<iframe>` tags
- `scope` for screen readers
- `span` for `<colgroup>` tags
- Added support for defining `propTypes` in mixins
- Added `any`, `arrayOf`, `component`, `oneOfType`, `renderable`, `shape` to `React.PropTypes`
- Added support for `statics` on component spec for static component methods
- On all events, `.currentTarget` is now properly set
- On keyboard events, `.key` is now polyfilled in all browsers for special (non-printable) keys
- On clipboard events, `.clipboardData` is now polyfilled in IE
- On drag events, `.dataTransfer` is now present
- Added support for `onMouseOver` and `onMouseOut` in addition to the existing `onMouseEnter` and `onMouseLeave` events
- Added support for `onLoad` and `onError` on `<img>` elements
- Added support for `onReset` on `<form>` elements
- The `autoFocus` attribute is now polyfilled consistently on `input`, `select`, and `textarea`
#### Bug Fixes
- React no longer adds an `__owner__` property to each component's `props` object; passed-in props are now never mutated
- When nesting top-level components (e.g., calling `React.renderComponent` within `componentDidMount`), events now properly bubble to the parent component
- Fixed a case where nesting top-level components would throw an error when updating
- Passing an invalid or misspelled propTypes type now throws an error
- On mouse enter/leave events, `.target`, `.relatedTarget`, and `.type` are now set properly
- On composition events, `.data` is now properly normalized in IE9 and IE10
- CSS property values no longer have `px` appended for the unitless properties `columnCount`, `flex`, `flexGrow`, `flexShrink`, `lineClamp`, `order`, `widows`
- Fixed a memory leak when unmounting children with a `componentWillUnmount` handler
- Fixed a memory leak when `renderComponentToString` would store event handlers
- Fixed an error that could be thrown when removing form elements during a click handler
- Boolean attributes such as `disabled` are rendered without a value (previously `disabled="true"`, now simply `disabled`)
- `key` values containing `.` are now supported
- Shortened `data-reactid` values for performance
- Components now always remount when the `key` property changes
- Event handlers are attached to `document` only when necessary, improving performance in some cases
- Events no longer use `.returnValue` in modern browsers, eliminating a warning in Chrome
- `scrollLeft` and `scrollTop` are no longer accessed on document.body, eliminating a warning in Chrome
- General performance fixes, memory optimizations, improvements to warnings and error messages
### React with Addons
- `React.addons.TestUtils` was added to help write unit tests
- `React.addons.TransitionGroup` was renamed to `React.addons.CSSTransitionGroup`
- `React.addons.TransitionGroup` was added as a more general animation wrapper
- `React.addons.cloneWithProps` was added for cloning components and modifying their props
- Bug fix for adding back nodes during an exit transition for CSSTransitionGroup
- Bug fix for changing `transitionLeave` in CSSTransitionGroup
- Performance optimizations for CSSTransitionGroup
- On checkbox `<input>` elements, `checkedLink` is now supported for two-way binding
### JSX Compiler and react-tools Package
- Whitespace normalization has changed; now space between two tags on the same line will be preserved, while newlines between two tags will be removed
- The `react-tools` npm package no longer includes the React core libraries; use the `react` package instead.
- `displayName` is now added in more cases, improving error messages and names in the React Dev Tools
- Fixed an issue where an invalid token error was thrown after a JSX closing tag
- `JSXTransformer` now uses source maps automatically in modern browsers
- `JSXTransformer` error messages now include the filename and problematic line contents when a file fails to parse
It's exciting to see the number of real-world React applications and components skyrocket over the past months! This community round-up features a few examples of inspiring React applications and components.
## React in the Real World
### Facebook Lookback video editor
Large parts of Facebook's web frontend are already powered by React. The recently released Facebook [Lookback video and its corresponding editor](https://www.facebook.com/lookback/edit/) are great examples of a complex, real-world React app.
### Russia's largest bank is now powered by React
Sberbank, Russia's largest bank, recently switched large parts of their site to use React, as detailed in [this post by Vyacheslav Slinko](https://groups.google.com/forum/#!topic/reactjs/Kj6WATX0atg).
### Relato
[Relato](http://bripkens.github.io/relato/) by [Ben Ripkens](https://github.com/bripkens) shows Open Source Statistics based on npm data. It features a filterable and sortable table built in React. Check it out – it's super fast!
### Makona Editor
John Lynch ([@johnrlynch](https://twitter.com/johnrlynch)) created Makona, a block-style document editor for the web. Blocks of different content types comprise documents, authored using plain markup. At the switch of a toggle, block contents are then rendered on the page. While not quite a WYSIWYG editor, Makona uses plain textareas for input. This makes it compatible with a wider range of platforms than traditional rich text editors.
React is in no way limited to just web pages. Brandon Tilley ([@BinaryMuse](https://twitter.com/BinaryMuse)) just released a detailed walk-through of [how he built his Chrome extension "Fast Tab Switcher" using React](http://brandontilley.com/2014/02/24/creating-chrome-extensions-with-react.html).
### Twitter Streaming Client
Javier Aguirre ([@javaguirre](https://twitter.com/javaguirre)) put together a simple [twitter streaming client using node, socket.io and React](http://javaguirre.net/2014/02/11/twitter-streaming-api-with-node-socket-io-and-reactjs/).
### Sproutsheet
[Sproutsheet](http://sproutsheet.com/) is a gardening calendar. You can use it to track certain events that happen in the life of your plants. It's currently in beta and supports localStorage, and data/image import and export.
### Instant Domain Search
[Instant Domain Search](https://instantdomainsearch.com/) also uses React. It sure is instant!
### SVG-based graphical node editor
[NoFlo](http://noflojs.org/) and [Meemoo](http://meemoo.org/) developer [Forresto Oliphant](http://www.forresto.com/) built an awesome SVG-based [node editor](http://forresto.github.io/prototyping/react/) in React.
Rafał Cieślak ([@Ravicious](https://twitter.com/Ravicious)) wrote a [React version](http://ravicious.github.io/ultimate-ttt/) of [Ultimate Tic Tac Toe](http://mathwithbaddrawings.com/2013/06/16/ultimate-tic-tac-toe/). Find the source [here](https://github.com/ravicious/ultimate-ttt).
### ReactJS Gallery
[Emanuele Rampichini](https://github.com/lele85)'s [ReactJS Gallery](https://github.com/lele85/ReactGallery) is a cool demo app that shows fullscreen images from a folder on the server. If the folder content changes, the gallery app updates via websockets.
[Table Sorter](http://bgerm.github.io/react-table-sorter-demo/) by [bgerm](https://github.com/bgerm) [[source](https://github.com/bgerm/react-table-sorter-demo)] is another helpful React component.
### Static-search
Dmitry Chestnykh [@dchest](https://twitter.com/dchest) wrote a [static search indexer](https://github.com/dchest/static-search) in Go, along with a [React-based web front-end](http://www.codingrobots.com/search/) that consumes search result via JSON.
### Lorem Ipsum component
[Martin Andert](https://github.com/martinandert) created [react-lorem-component](https://github.com/martinandert/react-lorem-component), a simple component for all your placeholding needs.
### Input with placeholder shim
[react-input=placeholder](https://github.com/enigma-io/react-input-placeholder) by [enigma-io](https://github.com/enigma-io) is a small wrapper around React.DOM.input that shims in placeholder functionality for browsers that don't natively support it.
### diContainer
[dicontainer](https://github.com/SpektrumFM/dicontainer) provides a dependency container that lets you inject Angular-style providers and services as simple React.js Mixins.
## React server rendering
Ever wonder how to pre-render React components on the server? [react-server-example](https://github.com/mhart/react-server-example) by Michael Hart ([@hichaelmart](http://twitter.com/hichaelmart)) walks through the necessary steps.
Similarly, Alan deLevie ([@adelevie](https://twitter.com/adelevie)) created [react-client-server-starter](https://github.com/adelevie/react-client-server-starter), another detailed walk-through of how to server-render your app.
## Random Tweet
<div><blockquote class="twitter-tweet" lang="en"><p>Recent changes: web ui is being upgraded to [#reactjs](https://twitter.com/search?q=%23reactjs&src=hash), HEAD~4 at [https://camlistore.googlesource.com/camlistore/](https://camlistore.googlesource.com/camlistore/)</p>— Camlistore (@Camlistore) <a href="https://twitter.com/Camlistore/status/423925795820539904">January 16, 2014</a></blockquote></div>
In this Round-up, we are taking a few closer looks at React's interplay with different frameworks and architectures.
## "Little framework BIG splash"
Let's start with yet another refreshing introduction to React: Craig Savolainen ([@maedhr](https://twitter.com/maedhr)) walks through some first steps, demonstrating [how to build a Google Maps component](http://infinitemonkeys.influitive.com/little-framework-big-splash) using React.
[Architecting your app with react](http://lincolnloop.com/blog/architecting-your-app-react-part-1/)
We're looking forward to part 2!
> React is not a full MVC framework, and this is actually one of its strengths. Many who adopt React choose to do so alongside their favorite MVC framework, like Backbone. React has no opinions about routing or syncing data, so you can easily use your favorite tools to handle those aspects of your frontend application. You'll often see React used to manage specific parts of an application's UI and not others. React really shines, however, when you fully embrace its strategies and make it the core of your application's interface.
>
> [Read the full article...](http://lincolnloop.com/blog/architecting-your-app-react-part-1/)
## React vs. async DOM manipulation
Eliseu Monar ([@eliseumds](https://twitter.com/eliseumds))'s post "[ReactJS vs async concurrent rendering](http://eliseu.tk/post/77843550010/vitalbox-pchr-reactjs-vs-async-concurrent-rendering)" is a great example of how React quite literally renders a whole array of common web development work(arounds) obsolete.
## React, Scala and the Play Framework
[Matthias Nehlsen](http://matthiasnehlsen.com/) wrote a detailed introductory piece on [React and the Play Framework](http://matthiasnehlsen.com/blog/2014/01/05/play-framework-and-facebooks-react-library/), including a helpful architectural diagram of a typical React app.
Nehlsen's React frontend is the second implementation of his chat application's frontend, following an AngularJS version. Both implementations are functionally equivalent and offer some perspective on differences between the two frameworks.
In [another article](http://matthiasnehlsen.com/blog/2014/01/24/scala-dot-js-and-reactjs/), he walks us through the process of using React with scala.js to implement app-wide undo functionality.
Also check out his [talk](http://m.ustream.tv/recorded/42780242) at Ping Conference 2014, in which he walks through a lot of the previously content in great detail.
## React and Backbone
The folks over at [Venmo](https://venmo.com/) are using React in conjunction with Backbone.
Thomas Boyt ([@thomasaboyt](https://twitter.com/thomasaboyt)) wrote [this detailed piece](http://www.thomasboyt.com/2013/12/17/using-reactjs-as-a-backbone-view.html) about why React and Backbone are "a fantastic pairing".
## React vs. Ember
Eric Berry ([@coderberry](https://twitter.com/coderberry)) developed Ember equivalents for some of the official React examples. Read his post for a side-by-side comparison of the respective implementations: ["Facebook React vs. Ember"](http://instructure.github.io/blog/2013/12/17/facebook-react-vs-ember/).
## React and plain old HTML
Daniel Lo Nigro ([@Daniel15](https://twitter.com/Daniel15)) created [React-Magic](https://github.com/reactjs/react-magic), which leverages React to ajaxify plain old html pages and even [allows CSS transitions between pageloads](http://stuff.dan.cx/facebook/react-hacks/magic/red.php).
> React-Magic intercepts all navigation (link clicks and form posts) and loads the requested page via an AJAX request. React is then used to "diff" the old HTML with the new HTML, and only update the parts of the DOM that have been changed.
>
> [Check out the project on GitHub...](https://github.com/reactjs/react-magic)
On a related note, [Reactize](https://turbo-react.herokuapp.com/) by Ross Allen ([@ssorallen](https://twitter.com/ssorallen)) is a similarly awesome project: A wrapper for Rails' [Turbolinks](https://github.com/rails/turbolinks/), which seems to have inspired John Lynch ([@johnrlynch](https://twitter.com/johnrlynch)) to then create [a server-rendered version using the JSX transformer in Rails middleware](http://www.rigelgroupllc.com/blog/2014/01/12/react-jsx-transformer-in-rails-middleware/).
## React and Object.observe
Check out [François de Campredon](https://github.com/fdecampredon)'s implementation of [TodoMVC based on React and ES6's Object.observe](https://github.com/fdecampredon/react-observe-todomvc/).
## React and Angular
Ian Bicking ([@ianbicking](https://twitter.com/ianbicking)) of Mozilla Labs [explains why he "decided to go with React instead of Angular.js"](https://plus.google.com/+IanBicking/posts/Qj8R5SWAsfE).
### ng-React Update
[David Chang](https://github.com/davidchang) works through some performance improvements of his [ngReact](https://github.com/davidchang/ngReact) project. His post ["ng-React Update - React 0.9 and Angular Track By"](http://davidandsuzi.com/ngreact-update/) includes some helpful advice on boosting render performance for Angular components.
> Angular gives you a ton of functionality out of the box - a full MV* framework - and I am a big fan, but I'll admit that you need to know how to twist the right knobs to get performance.
>
> That said, React gives you a very strong view component out of the box with the performance baked right in. Try as I did, I couldn't actually get it any faster. So pretty impressive stuff.
>
>[Read the full post...](http://davidandsuzi.com/ngreact-update/)
React was also recently mentioned at ng-conf, where the Angular team commented on React's concept of the virtual DOM:
Jonathan Krause ([@jonykrause](https://twitter.com/jonykrause)) offers his thoughts regarding [parallels between React and Web Components](http://jonykrau.se/posts/the-value-of-react), highlighting the value of React's ability to render pages on the server practically for free.
## Immutable React
[Peter Hausel](http://pk11.kinja.com/) shows how to build a Wikipedia auto-complete demo based on immutable data structures (similar to [mori](https://npmjs.org/package/mori)), really taking advantage of the framework's one-way reactive data binding:
> Its truly reactive design makes DOM updates finally sane and when combined with persistent data structures one can experience JavaScript development like it was never done before.
> [Read the full post](http://tech.kinja.com/immutable-react-1495205675)
## D3 and React
[Ben Smith](http://10consulting.com/) built some great SVG-based charting components using a little less of D3 and a little more of React: [D3 and React - the future of charting components?](http://10consulting.com/2014/02/19/d3-plus-reactjs-for-charting/)
## Om and React
Josh Haberman ([@joshhaberman](https://twitter.com/JoshHaberman)) discusses performance differences between React, Om and traditional MVC frameworks in "[A closer look at OM vs React performance](http://blog.reverberate.org/2014/02/on-future-of-javascript-mvc-frameworks.html)".
Speaking of Om: [Omchaya](https://github.com/sgrove/omchaya) by Sean Grove ([@sgrove](https://twitter.com/sgrove)) is a neat Cljs/Om example project.
## Random Tweets
<div><blockquote class="twitter-tweet" lang="en"><p>Worked for 2 hours on a [@react_js](https://twitter.com/react_js) app sans internet. Love that I could get stuff done with it without googling every question.</p>— John Shimek (@varikin) <a href="https://twitter.com/varikin/status/436606891657949185">February 20, 2014</a></blockquote></div>
[v0.9 has only been out for a month](http://facebook.github.io/react/blog/2014/02/20/react-v0.9.html), but we’re getting ready to push out v0.10 already. Unlike v0.9 which took a long time, we don't have a long list of changes to talk about.
The release candidate is available for download from the CDN:
* **React**
Dev build with warnings: <http://fb.me/react-0.10.0-rc1.js>
Minified build for production: <http://fb.me/react-0.10.0-rc1.min.js>
***React with Add-Ons**
Dev build with warnings: <http://fb.me/react-with-addons-0.10.0-rc1.js>
Minified build for production: <http://fb.me/react-with-addons-0.10.0-rc1.min.js>
***In-Browser JSX transformer**
<http://fb.me/JSXTransformer-0.10.0-rc1.js>
We've also published version `0.10.0-rc1` of the `react` and `react-tools` packages on npm and the `react` package on bower.
Please try these builds out and [file an issue on GitHub](https://github.com/facebook/react/issues/new) if you see anything awry.
## Clone On Mount
The main purpose of this release is to provide a smooth upgrade path as we evolve some of the implementation of core. In v0.9 we started warning in cases where you called methods on unmounted components. This is part of an effort to enforce the idea that the return value of a component (`React.DOM.div()`, `MyComponent()`) is in fact not a reference to the component instance React uses in the virtual DOM. The return value is instead a light-weight object that React knows how to use. Since the return value currently is a reference to the same object React uses internally, we need to make this transition in stages as many people have come to depend on this implementation detail.
In 0.10, we’re adding more warnings to catch a similar set of patterns. When a component is mounted we clone it and use that object for our internal representation. This allows us to capture calls you think you’re making to a mounted component. We’ll forward them on to the right object, but also warn you that this is breaking. See “Access to the Mounted Instance” on [this page](http://fb.me/react-warning-descriptors). Most of the time you can solve your pattern by using refs.
Storing a reference to your top level component is a pattern touched upon on that page, but another examples that demonstrates what we see a lot of:
```js
// This is a common pattern. However instance here really refers to a
// "descriptor", not necessarily the mounted instance.
varinstance=<MyComponent/>;
React.renderComponent(instance);
// ...
instance.setProps(...);
// The change here is very simple. The return value of renderComponent will be
// the mounted instance.
varinstance=React.renderComponent(<MyComponent/>)
// ...
instance.setProps(...);
```
These warnings and method forwarding are only enabled in the development build. The production builds continue to work as they did in v0.9. We strongly encourage you to use the development builds to catch these warnings and fix the call sites.
The plan for v0.11 is that we will go fully to "descriptors". Method calls on the return value of `MyComponent()` will fail hard.
## Changelog
### React Core
#### New Features
* Made it possible to server render without React-related markup (`data-reactid`, `data-react-checksum`) - `React.renderComponentToStaticMarkup`
* Added support for more attributes:
*`srcSet` for `<img>` to images at different pixel ratios
*`textAnchor` for SVG
#### Bug Fixes
* Ensure all void elements don’t insert a closing tag into the markup.
* Ensure `className={false}` behaves consistently
* Ensure `this.refs` is defined, even if no refs are specified.
### Addons
*`update` function to deal with immutable data.
### react-tools
* Added an option argument to `transform` function. The only option supported is `harmony`, which behaves the same as `jsx --harmony` on the command line. This uses the ES6 transforms from [jstransform](https://github.com/facebook/jstransform).
React is a JavaScript library for creating user interfaces by Facebook and Instagram. Many people choose to think of React as the **V** in **[MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)**.
We built React to solve one problem: **building large applications with data that changes over time**. To do this, React uses two main ideas.
### Simple
Simply express how your app should look at any given point in time, and React will automatically manage all UI updates when your underlying data changes.
### Declarative
When the data changes, React conceptually hits the "refresh" button, and knows to only update the changed parts.
## Build Composable Components
React is all about building reusable components. In fact, with React the *only* thing you do is build components. Since they're so encapsulated, components make code reuse, testing, and separation of concerns easy.
## Give It Five Minutes
React challenges a lot of conventional wisdom, and at first glance some of the ideas may seem crazy. [Give it five minutes](http://37signals.com/svn/posts/3124-give-it-five-minutes) while reading this guide; those crazy ideas have worked for building thousands of components both inside and outside of Facebook and Instagram.
## Learn More
You can learn more about our motivations behind building React in [this blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html).
The most basic thing you can do with a UI is display some data. React makes it easy to display data and automatically keeps the interface up-to-date when the data changes.
## Getting Started
Let's look at a really simple example. Create a `hello-react.html` file with the following code:
For the rest of the documentation, we'll just focus on the JavaScript code and assume it's inserted into a template like the one above. Replace the placeholder comment above with the following JS:
```javascript
/** @jsx React.DOM */
varHelloWorld=React.createClass({
render:function(){
return(
<p>
Hello,<inputtype="text"placeholder="Your name here"/>!
Itis{this.props.date.toTimeString()}
</p>
);
}
});
setInterval(function(){
React.renderComponent(
<HelloWorlddate={newDate()}/>,
document.getElementById('example')
);
},500);
```
## Reactive Updates
Open `hello-react.html` in a web browser and type your name into the text field. Notice that React is only changing the time string in the UI — any input you put in the text field remains, even though you haven't written any code to manage this behavior. React figures it out for you and does the right thing.
The way we are able to figure this out is that React does not manipulate the DOM unless it needs to. **It uses a fast, internal mock DOM to perform diffs and computes the most efficient DOM mutation for you.**
The inputs to this component are called `props` — short for "properties". They're passed as attributes in JSX syntax. You should think of these as immutable within the component, that is, **never write to `this.props`**.
## Components are Just Like Functions
React components are very simple. You can think of them as simple function that take in `props` and `state` (discussed later) and render HTML. Because they're so simple, it makes them very easy to reason about.
> Note:
>
> **One limitation**: React components can only render a single root node. If you want to return multiple nodes they *must* be wrapped in a single root.
## JSX Syntax
We strongly believe that components are the right way to separate concerns rather than "templates" and "display logic." We think that markup and the code that generates it are intimately tied together. Additionally, display logic is often very complex and using template languages to express it becomes cumbersome.
We've found that the best solution for this problem is to generate markup directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs. In order to make this easier, we've added a very simple, **optional** HTML-like syntax for the function calls that generate markup called JSX.
**JSX lets you write JavaScript function calls with HTML syntax.** To generate a link in React using pure JavaScript you'd write: `React.DOM.a({href: 'http://facebook.github.io/react/'}, 'Hello React!')`. With JSX this becomes `<a href="http://facebook.github.io/react/">Hello React!</a>`. We've found this has made building React apps easier and designers tend to prefer the syntax, but everyone has their own workflow, so **JSX is not required to use React.**
JSX is very small; the "hello, world" example above uses every feature of JSX. To learn more about it, see [JSX in depth](/react/docs/jsx-in-depth.html). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
JSX is similar to HTML, but not exactly the same. See [JSX gotchas](/react/docs/jsx-gotchas.html) for some key differences.
The easiest way to get started with JSX is to use the in-browser `JSXTransformer`. We strongly recommend that you don't use this in production. You can precompile your code using our command-line [react-tools](http://npmjs.org/package/react-tools) package.
JSX is a JavaScript XML syntax transform recommended (but not required) for use
JSX is a JavaScript XML syntax transform recommended for use
with React.
## Why JSX?
> Note:
>
> Don't forget the `/** @jsx React.DOM */` pragma at the beginning of your file! This tells JSX to process the file for React.
>
> If you don't include the pragma, your source will remain untouched, so it's safe to run the JSX transformer on all JS files in your codebase if you want to.
First of all, **don't use JSX if you don't like it!**
## Why JSX?
React works out of the box without JSX. Simply construct your markup using the
functions on `React.DOM`. For example, here's how to construct a simple link:
@@ -23,21 +27,22 @@ var link = React.DOM.a({href: 'http://facebook.github.io/react'}, 'React');
We recommend using JSX for many reasons:
- It's easier to visualize the structure of the DOM.
- Designers are more comfortable making changes.
- It's familiar for those who have used MXML or XAML.
* It's easier to visualize the structure of the DOM.
* Designers are more comfortable making changes.
* It's familiar for those who have used MXML or XAML.
## The Transform
JSX transforms XML-like syntax into native JavaScript. It turns XML elements and
attributes into function calls and objects, respectively.
JSX transforms from an XML-like syntax into native JavaScript. XML elements and
attributes are transformed into function calls and objects, respectively.
```javascript
var Nav;
// Input (JSX):
var app = <Nav color="blue" />;
// Output (JS):
var app = Nav({color:'blue'});
var app = Nav({color:"blue"});
```
Notice that in order to use `<Nav />`, the `Nav` variable must be in scope.
@@ -49,13 +54,15 @@ var Nav, Profile;
// Input (JSX):
var app = <Nav color="blue"><Profile>click</Profile></Nav>;
// Output (JS):
var app = Nav({color:'blue'}, Profile({}, 'click'));
var app = Nav({color:"blue"}, Profile(null, "click"));
```
Use the [JSX Compiler](/react/jsx-compiler.html) to try out JSX and see how it
desguars into native JavaScript.
desugars into native JavaScript, and the
[HTML to JSX converter](/react/html-jsx.html) to convert your existing HTML to
JSX.
If you want to use JSX, the [Getting Started](getting-started.html) guide shows
If you want to use JSX, the [Getting Started](/react/docs/getting-started.html) guide shows
how to setup compilation.
> Note:
@@ -63,16 +70,17 @@ how to setup compilation.
> Details about the code transform are given here to increase understanding, but
> your code should not rely on these implementation details.
## React and JSX
React and JSX are independent technologies, but JSX was primarily built with
React in mind. The two valid uses of JSX are:
- To construct instances of React DOM components (`React.DOM.*`).
- To construct instances of composite components created with
* To construct instances of React DOM components (`React.DOM.*`).
* To construct instances of composite components created with
`React.createClass()`.
**React DOM Components**
### React DOM Components
To construct a `<div>` is to create a variable that refers to `React.DOM.div`.
@@ -81,7 +89,7 @@ var div = React.DOM.div;
var app = <div className="appClass">Hello, React!</div>;
```
**React Component Components**
### React Composite Components
To construct an instance of a composite component, create a variable that
references the class.
@@ -91,7 +99,10 @@ var MyComponent = React.createClass({/*...*/});
var app = <MyComponent someProperty={true} />;
```
See [Component Basics](component-basics.html) to learn more about components.
JSX will infer the component's name from the variable assignment and specify
the class's [displayName](/react/docs/component-specs.html#displayName) accordingly.
See [Multiple Components](/react/docs/multiple-components.html) to learn more about using composite components.
> Note:
>
@@ -114,7 +125,7 @@ var Nav;
// Input (JSX):
var tree = <Nav><span /></Nav>;
// Output (JS):
var tree = Nav({}, React.DOM.span({}));
var tree = Nav(null, React.DOM.span(null));
```
> Remember:
@@ -125,7 +136,7 @@ var tree = Nav({}, React.DOM.span({}));
## JavaScript Expressions
#### Attribute Expressions
### Attribute Expressions
To use a JavaScript expression as an attribute value, wrap the expression in a
pair of curly braces (`{}`) instead of quotes (`""`).
@@ -137,7 +148,7 @@ var person = <Person name={window.isLoggedIn ? window.name : ''} />;
var person = Person({name: window.isLoggedIn ? window.name : ''});
```
#### Child Expressions
### Child Expressions
Likewise, JavaScript expressions may be used to express children:
@@ -145,17 +156,17 @@ Likewise, JavaScript expressions may be used to express children:
// Input (JSX):
var content = <Container>{window.isLoggedIn ? <Nav /> : <Login />}</Container>;
JSX looks like HTML but there are some important differences you may run into.
> Note:
>
> For DOM differences, such as the inline `style` attribute, check [here](/react/docs/dom-differences.html).
## HTML Entities
You can insert HTML entities within literal text in JSX:
```javascript
<div>First·Second</div>
```
If you want to display an HTML entity within dynamic content, you will run into double escaping issues as React escapes all the strings you are displaying in order to prevent a wide range of XSS attacks by default.
```javascript
// Bad: It displays "First · Second"
<div>{'First · Second'}</div>
```
There are various ways to work-around this issue. The easiest one is to write unicode character directly in Javascript. You need to make sure that the file is saved as UTF-8 and that the proper UTF-8 directives are set so the browser will display it correctly.
```javascript
<div>{'First · Second'}</div>
```
A safer alternative is to find the [unicode number corresponding to the entity](http://www.fileformat.info/info/unicode/char/b7/index.htm) and use it inside of a JavaScript string.
If you pass properties to native HTML elements that do not exist in the HTML specification, React will not render them. If you want to use a custom attribute, you should prefix it with `data-`.
```javascript
<divdata-custom-attribute="foo"/>
```
[Web Accessibility](http://www.w3.org/WAI/intro/aria) attributes starting with `aria-` will be rendered properly.
You've already [learned how to display data](/react/docs/displaying-data.html) with React. Now let's look at how to make our UIs interactive.
## A Simple Example
```javascript
/** @jsx React.DOM */
varLikeButton=React.createClass({
getInitialState:function(){
return{liked:false};
},
handleClick:function(event){
this.setState({liked:!this.state.liked});
},
render:function(){
vartext=this.state.liked?'like':'unlike';
return(
<ponClick={this.handleClick}>
You{text}this.Clicktotoggle.
</p>
);
}
});
React.renderComponent(
<LikeButton/>,
document.getElementById('example')
);
```
## Event Handling and Synthetic Events
With React you simply pass your event handler as a camelCased prop similar to how you'd do it in normal HTML. React ensures that all events behave identically in IE8 and above by implementing a synthetic event system. That is, React knows how to bubble and capture events according to the spec, and the events passed to your event handler are guaranteed to be consistent with [the W3C spec](http://www.w3.org/TR/DOM-Level-3-Events/), regardless of which browser you're using.
If you'd like to use React on a touch device (i.e. a phone or tablet), simply call `React.initializeTouchEvents(true);` to turn them on.
## Under the Hood: Autobinding and Event Delegation
Under the hood React does a few things to keep your code performant and easy to understand.
**Autobinding:** When creating callbacks in JavaScript you usually need to explicitly bind a method to its instance such that the value of `this` is correct. With React, every method is automatically bound to its component instance. React caches the bound method such that it's extremely CPU and memory efficient. It's also less typing!
**Event delegation:** React doesn't actually attach event handlers to the nodes themselves. When React starts up, it starts listening for all events at the top level using a single event listener. When a component is mounted or unmounted, the event handlers are simply added or removed from an internal mapping. When an event occurs, React knows how to dispatch it using this mapping. When there are no event handlers left in the mapping, React's event handlers are simple no-ops. To learn more about why this is fast, see [David Walsh's excellent blog post](http://davidwalsh.name/event-delegate).
## Components are Just State Machines
React thinks of UIs as simple state machines. By thinking of a UI as being in various states and rendering those states, it's easy to keep your UI consistent.
In React, you simply update a component's state, and then render a new UI based on this new state. React takes care of updating the DOM for you in the most efficient way.
## How State Works
A common way to inform React of a data change is by calling `setState(data, callback)`. This method merges `data` into `this.state` and re-renders the component. When the component finishes re-rendering, the optional `callback` is called. Most of the time you'll never need to provide a `callback` since React will take care of keeping your UI up-to-date for you.
## What Components Should Have State?
Most of your components should simply take some data from `props` and render it. However, sometimes you need to respond to user input, a server request or the passage of time. For this you use state.
**Try to keep as many of your components as possible stateless.** By doing this you'll isolate the state to its most logical place and minimize redundancy, making it easier to reason about your application.
A common pattern is to create several stateless components that just render data, and have a stateful component above them in the hierarchy that passes its state to its children via `props`. The stateful component encapsulates all of the interaction logic, while the stateless components take care of rendering data in a declarative way.
## What *Should* Go in State?
**State should contain data that a component's event handlers may change to trigger a UI update.** In real apps this data tends to be very small and JSON-serializable. When building a stateful component, think about the minimal possible representation of its state, and only store those properties in `this.state`. Inside of `render()` simply compute any other information you need based on this state. You'll find that thinking about and writing applications in this way tends to lead to the most correct application, since adding redundant or computed values to state means that you need to explicitly keep them in sync rather than rely on React computing them for you.
## What *Shouldn't* Go in State?
`this.state` should only contain the minimal amount of data needed to represent your UI's state. As such, it should not contain:
* **Computed data:** Don't worry about precomputing values based on state — it's easier to ensure that your UI is consistent if you do all computation within `render()`. For example, if you have an array of list items in state and you want to render the count as a string, simply render `this.state.listItems.length + ' list items'` in your `render()` method rather than storing it on state.
* **React components:** Build them in `render()` based on underlying props and state.
* **Duplicated data from props:** Try to use props as the source of truth where possible. Because props can change over time, it's appropriate to store props in state to be able to know its previous values.
So far, we've looked at how to write a single component to display data and handle user input. Next let's examine one of React's finest features: composability.
## Motivation: Separation of Concerns
By building modular components that reuse other components with well-defined interfaces, you get much of the same benefits that you get by using functions or classes. Specifically you can *separate the different concerns* of your app however you please simply by building new components. By building a custom component library for your application, you are expressing your UI in a way that best fits your domain.
## Composition Example
Let's create a simple Avatar component which shows a profile picture and username using the Facebook Graph API.
In the above example, instances of `Avatar`*own* instances of `ProfilePic` and `ProfileLink`. In React, **an owner is the component that sets the `props` of other components**. More formally, if a component `X` is created in component `Y`'s `render()` method, it is said that `X` is *owned by*`Y`. As discussed earlier, a component cannot mutate its `props` — they are always consistent with what its owner sets them to. This key property leads to UIs that are guaranteed to be consistent.
It's important to draw a distinction between the owner-ownee relationship and the parent-child relationship. The owner-ownee relationship is specific to React, while the parent-child relationship is simply the one you know and love from the DOM. In the example above, `Avatar` owns the `div`, `ProfilePic` and `ProfileLink` instances, and `div` is the **parent** (but not owner) of the `ProfilePic` and `ProfileLink` instances.
## Children
When you create a React component instance, you can include additional React components or JavaScript expressions between the opening and closing tags like this:
```javascript
<Parent><Child/></Parent>
```
`Parent` can read its children by accessing the special `this.props.children` prop. **`this.props.children` is an opaque data structure:** use the [React.Children utilities](/react/docs/top-level-api.html#react.children) to manipulate them.
### Child Reconciliation
**Reconciliation is the process by which React updates the DOM with each new render pass.** In general, children are reconciled according to the order in which they are rendered. For example, suppose two render passes generate the following respective markup:
```html
// Render Pass 1
<Card>
<p>Paragraph 1</p>
<p>Paragraph 2</p>
</Card>
// Render Pass 2
<Card>
<p>Paragraph 2</p>
</Card>
```
Intuitively, `<p>Paragraph 1</p>` was removed. Instead, React will reconcile the DOM by changing the text content of the first child and destroying the last child. React reconciles according to the *order* of the children.
### Stateful Children
For most components, this is not a big deal. However, for stateful components that maintain data in `this.state` across render passes, this can be very problematic.
In most cases, this can be sidestepped by hiding elements instead of destroying them:
```html
// Render Pass 1
<Card>
<p>Paragraph 1</p>
<p>Paragraph 2</p>
</Card>
// Render Pass 2
<Card>
<pstyle={{'{{'}}display:'none'}}>Paragraph 1</p>
<p>Paragraph 2</p>
</Card>
```
### Dynamic Children
The situation gets more complicated when the children are shuffled around (as in search results) or if new components are added onto the front of the list (as in streams). In these cases where the identity and state of each child must be maintained across render passes, you can uniquely identify each child by assigning it a `key`:
```javascript
render:function(){
varresults=this.props.results;
return(
<ol>
{results.map(function(result){
return<likey={result.id}>{result.text}</li>;
})}
</ol>
);
}
```
When React reconciles the keyed children, it will ensure that any child with `key` will be reordered (instead of clobbered) or destroyed (instead of reused).
You can also key children by passing an object. The object keys will be used as `key` for each value. However it is important to remember that JavaScript does not guarantee the ordering of properties will be preserved. In practice browsers will preserve property order **except** for properties that can be parsed as a 32-bit unsigned integers. Numeric properties will be ordered sequentially and before other properties. If this happens React will render components out of order. This can be avoided by adding a string prefix to the key:
```javascript
render:function(){
varitems={};
this.props.results.forEach(function(result){
// If result.id can look like a number (consider short hashes), then
// object iteration order is not guaranteed. In this case, we add a prefix
In React, data flows from owner to owned component through `props` as discussed above. This is effectively one-way data binding: owners bind their owned component's props to some value the owner has computed based on its `props` or `state`. Since this process happens recursively, data changes are automatically reflected everywhere they are used.
## A Note on Performance
You may be thinking that it's expensive to react to changing data if there are a large number of nodes under an owner. The good news is that JavaScript is fast and `render()` methods tend to be quite simple, so in most applications this is extremely fast. Additionally, the bottleneck is almost always the DOM mutation and not JS execution and React will optimize this for you using batching and change detection.
However, sometimes you really want to have fine-grained control over your performance. In that case, simply override `shouldComponentUpdate()` to return false when you want React to skip processing of a subtree. See [the React reference docs](/react/docs/component-specs.html) for more information.
> Note:
>
> If `shouldComponentUpdate()` returns false when data has actually changed, React can't keep your UI in sync. Be sure you know what you're doing while using it, and only use this function when you have a noticeable performance problem. Don't underestimate how fast JavaScript is relative to the DOM.
When designing interfaces, break down the common design elements (buttons, form fields, layout components, etc) into reusable components with well-defined interfaces. That way, the next time you need to build some UI you can write much less code, which means faster development time, less bugs, and less bytes down the wire.
## Prop Validation
As your app grows it's helpful to ensure that your components are used correctly. We do this by allowing you to specify `propTypes`. `React.PropTypes` exports a range of validators that can be used to make sure the data you receive is valid. When an invalid value is provided for a prop, a warning will be shown in the JavaScript console. Note that for performance reasons `propTypes` is only checked in development mode. Here is an example documenting the different validators provided:
```javascript
React.createClass({
propTypes:{
// You can declare that a prop is a specific JS primitive. By default, these
// are all optional.
optionalArray:React.PropTypes.array,
optionalBool:React.PropTypes.bool,
optionalFunc:React.PropTypes.func,
optionalNumber:React.PropTypes.number,
optionalObject:React.PropTypes.object,
optionalString:React.PropTypes.string,
// Anything that can be rendered: numbers, strings, components or an array
// containing these types.
optionalRenderable:React.PropTypes.renderable,
// A React component.
optionalComponent:React.PropTypes.component,
// You can also declare that a prop is an instance of a class. This uses
React lets you define default values for your `props` in a very declarative way:
```javascript
varComponentWithDefaultProps=React.createClass({
getDefaultProps:function(){
return{
value:'default value'
};
}
/* ... */
});
```
The result of `getDefaultProps()` will be cached and used to ensure that `this.props.value` will have a value if it was not specified by the parent component. This allows you to safely just use your props without having to write repetitive and fragile code to handle that yourself.
## Transferring Props: A Shortcut
A common type of React component is one that extends a basic HTML in a simple way. Often you'll want to copy any HTML attributes passed to your component to the underlying HTML element to save typing. React provides `transferPropsTo()` to do just this.
```javascript
/** @jsx React.DOM */
varCheckLink=React.createClass({
render:function(){
// transferPropsTo() will take any props passed to CheckLink
With `React.PropTypes.component` you can specify that only a single child can be passed to
a component as children.
```javascript
varMyComponent=React.createClass({
propTypes:{
children:React.PropTypes.component.isRequired
},
render:function(){
return
<div>
{this.props.children}// This must be exactly one element or it will throw.
</div>;
}
});
```
## Mixins
Components are the best way to reuse code in React, but sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](http://en.wikipedia.org/wiki/Cross-cutting_concern). React provides `mixins` to solve this problem.
One common use case is a component wanting to update itself on a time interval. It's easy to use `setInterval()`, but it's important to cancel your interval when you don't need it anymore to save memory. React provides [lifecycle methods](/react/docs/working-with-the-browser.html#component-lifecycle) that let you know when a component is about to be created or destroyed. Let's create a simple mixin that uses these methods to provide an easy `setInterval()` function that will automatically get cleaned up when your component is destroyed.
A nice feature of mixins is that if a component is using multiple mixins and several mixins define the same lifecycle method (i.e. several mixins want to do some cleanup when the component is destroyed), all of the lifecycle methods are guaranteed to be called.
Form components such as `<input>`, `<textarea>`, and `<option>` differ from other native components because they can be mutated via user interactions. These components provide interfaces that make it easier to manage forms in response to user interactions.
## Interactive Props
Form components support a few props that are affected via user interactions:
*`value`, supported by `<input>` and `<textarea>` components.
*`checked`, supported by `<input>` components of type `checkbox` or `radio`.
*`selected`, supported by `<option>` components.
In HTML, the value of `<textarea>` is set via children. In React, you should use `value` instead.
Form components allow listening for changes by setting a callback to the `onChange` prop. The `onChange` prop works across browsers to fire in response to user interactions when:
* The `value` of `<input>` or `<textarea>` changes.
* The `checked` state of `<input>` changes.
* The `selected` state of `<option>` changes.
Like all DOM events, the `onChange` prop is supported on all native components and can be used to listen to bubbled change events.
## Controlled Components
An `<input>` with `value` set is a *controlled* component. In a controlled `<input>`, the value of the rendered element will always reflect the `value` prop. For example:
```javascript
render:function(){
return<inputtype="text"value="Hello!"/>;
}
```
This will render an input that always has a value of `Hello!`. Any user input will have no effect on the rendered element because React has declared the value to be `Hello!`. If you wanted to update the value in response to user input, you could use the `onChange` event:
In this example, we are simply accepting the newest value provided by the user and updating the `value` prop of the `<input>` component. This pattern makes it easy to implement interfaces that respond to or validate user interactions. For example:
This would accept user input but truncate the value to the first 140 characters.
## Uncontrolled Components
An `<input>` that does not supply a `value` (or sets it to `null`) is an *uncontrolled* component. In an uncontrolled `<input>`, the value of the rendered element will reflect the user's input. For example:
```javascript
render:function(){
return<inputtype="text"/>;
}
```
This will render an input that starts off with an empty value. Any user input will be immediately reflected by the rendered element. If you wanted to listen to updates to the value, you could use the `onChange` event just like you can with controlled components.
If you want to initialize the component with a non-empty value, you can supply a `defaultValue` prop. For example:
```javascript
render:function(){
return<inputtype="text"defaultValue="Hello!"/>;
}
```
This example will function much like the **Controlled Components** example above.
Likewise, `<input>` supports `defaultChecked` and `<select>` supports `defaultValue`.
## Advanced Topics
### Why Controlled Components?
Using form components such as `<input>` in React presents a challenge that is absent when writing traditional form HTML. For example, in HTML:
```html
<inputtype="text"name="title"value="Untitled"/>
```
This renders an input *initialized* with the value, `Untitled`. When the user updates the input, the node's value *property* will change. However, `node.getAttribute('value')` will still return the value used at initialization time, `Untitled`.
Unlike HTML, React components must represent the state of the view at any point in time and not only at initialization time. For example, in React:
Since this method describes the view at any point in time, the value of the text input should *always* be `Untitled`.
### Why Textarea Value?
In HTML, the value of `<textarea>` is usually set using its children:
```html
<!-- counterexample: DO NOT DO THIS! -->
<textareaname="description">This is the description.</textarea>
```
For HTML, this easily allows developers to supply multiline values. However, since React is JavaScript, we do not have string limitations and can use `\n` if we want newlines. In a world where we have `value` and `defaultValue`, it is ambiguous what role children play. For this reason, you should not use children when setting `<textarea>` values:
```javascript
<textareaname="description"value="This is a description."/>
```
If you *do* decide to use children, they will behave like `defaultValue`.
### Why Select Value?
The selected `<option>` in an HTML `<select>` is normally specified through that option's `selected` attribute. In React, in order to make components easier to manipulate, the following format is adopted instead:
```javascript
<selectvalue="B">
<optionvalue="A">Apple</option>
<optionvalue="B">Banana</option>
<optionvalue="C">Cranberry</option>
</select>
```
To make an uncontrolled component, `defaultValue` is used instead.
React provides powerful abstractions that free you from touching the DOM directly in most cases, but sometimes you simply need to access the underlying API, perhaps to work with a third-party library or existing code.
## The Virtual DOM
React is so fast because it never talks to the DOM directly. React maintains a fast in-memory representation of the DOM. `render()` methods return a *description* of the DOM, and React can diff this description with the in-memory representation to compute the fastest way to update the browser.
Additionally, React implements a full synthetic event system such that all event objects are guaranteed to conform to the W3C spec despite browser quirks, and everything bubbles consistently and in a performant way cross-browser. You can even use some HTML5 events in IE8!
Most of the time you should stay within React's "faked browser" world since it's more performant and easier to reason about. However, sometimes you simply need to access the underlying API, perhaps to work with a third-party library like a jQuery plugin. React provides escape hatches for you to use the underlying DOM API directly.
## Refs and getDOMNode()
To interact with the browser, you'll need a reference to a DOM node. Every mounted React component has a `getDOMNode()` function which you can call to get a reference to it.
> Note:
>
> `getDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `getDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.
In order to get a reference to a React component, you can either use `this` to get the current React component, or you can use refs to refer to a component you own. They work like this:
```javascript
/** @jsx React.DOM */
varMyComponent=React.createClass({
handleClick:function(){
// Explicitly focus the text input using the raw DOM API.
this.refs.myTextInput.getDOMNode().focus();
},
render:function(){
// The ref attribute adds a reference to the component to
// this.refs when the component is mounted.
return(
<div>
<inputtype="text"ref="myTextInput"/>
<input
type="button"
value="Focus the text input"
onClick={this.handleClick}
/>
</div>
);
}
});
React.renderComponent(
<MyComponent/>,
document.getElementById('example')
);
```
## More About Refs
To learn more about refs, including ways to use them effectively, see our [more about refs](/react/docs/more-about-refs.html) documentation.
## Component Lifecycle
Components have three main parts of their lifecycle:
* **Mounting:** A component is being inserted into the DOM.
* **Updating:** A component is being re-rendered to determine if the DOM should be updated.
* **Unmounting:** A component is being removed from the DOM.
React provides lifecycle methods that you can specify to hook into this process. We provide **will** methods, which are called right before something happens, and **did** methods which are called right after something happens.
### Mounting
*`getInitialState(): object` is invoked before a component is mounted. Stateful components should implement this and return the initial state data.
*`componentWillMount()` is invoked immediately before mounting occurs.
*`componentDidMount()` is invoked immediately after mounting occurs. Initialization that requires DOM nodes should go here.
### Updating
*`componentWillReceiveProps(object nextProps)` is invoked when a mounted component receives new props. This method should be used to compare `this.props` and `nextProps` to perform state transitions using `this.setState()`.
*`shouldComponentUpdate(object nextProps, object nextState): boolean` is invoked when a component decides whether any changes warrant an update to the DOM. Implement this as an optimization to compare `this.props` with `nextProps` and `this.state` with `nextState` and return false if React should skip updating.
*`componentWillUpdate(object nextProps, object nextState)` is invoked immediately before updating occurs. You cannot call `this.setState()` here.
*`componentDidUpdate(object prevProps, object prevState)` is invoked immediately after updating occurs.
### Unmounting
*`componentWillUnmount()` is invoked immediately before a component is unmounted and destroyed. Cleanup should go here.
### Mounted Methods
_Mounted_ composite components also support the following methods:
*`getDOMNode(): DOMElement` can be invoked on any mounted component in order to obtain a reference to its rendered DOM node.
*`forceUpdate()` can be invoked on any mounted component when you know that some deeper aspect of the component's state has changed without using `this.setState()`.
## Browser Support and Polyfills
At Facebook, we support older browsers, including IE8. We've had polyfills in place for a long time to allow us to write forward-thinking JS. This means we don't have a bunch of hacks scattered throughout our codebase and we can still expect our code to "just work". For example, instead of seeing `+new Date()`, we can just write `Date.now()`. Since the open source React is the same as what we use internally, we've carried over this philosophy of using forward thinking JS.
In addition to that philosophy, we've also taken the stance that we, as authors of a JS library, should not be shipping polyfills as a part of our library. If every library did this, there's a good chance you'd be sending down the same polyfill multiple times, which could be a sizable chunk of dead code. If your product needs to support older browsers, chances are you're already using something like [es5-shim](https://github.com/kriskowal/es5-shim).
### Polyfills Needed to Support Older Browsers
`es5-shim.js` from [kriskowal's es5-shim](https://github.com/kriskowal/es5-shim) provides the following that React needs:
*`Array.isArray`
*`Array.prototype.forEach`
*`Array.prototype.indexOf`
*`Array.prototype.some`
*`Date.now`
*`Function.prototype.bind`
*`Object.keys`
`es5-sham.js`, also from [kriskowal's es5-shim](https://github.com/kriskowal/es5-shim), provides the following that React needs:
*`Object.create`
*`Object.freeze`
The unminified build of React needs the following from [paulmillr's console-polyfill](https://github.com/paulmillr/console-polyfill).
*`console.*`
When using HTML5 elements in IE8 including `<section>`, `<article>`, `<nav>`, `<header>`, and `<footer>`, it's also necessary to include [html5shiv](https://github.com/aFarkas/html5shiv) or a similar script.
### Cross-browser Issues
Although React is pretty good at abstracting browser differences, some browsers are limited or present quirky behaviors that we couldn't find a workaround for.
#### onScroll event on IE8
On IE8 the `onScroll` event doesn't bubble and IE8 doesn't have an API to define handlers to the capturing phase of an event, meaning there is no way for React to listen to these events.
Currently a handler to this event is ignored on IE8.
See the [onScroll doesn't work in IE8](https://github.com/facebook/react/issues/631) GitHub issue for more information.
After returning the structure of your UI from the render method, you may find yourself wanting to "reach out" and invoke methods on component instances returned from render. Often, doing something like this isn't necessary for making data flow through your application, because the Reactive data flow always ensures that the most recent `props` are sent to each child that is output from `render()`. However there are a few cases, where it still might be necessary or beneficial.
Consider the case when you wish to tell an `<input />` element (that exists within your instances sub-hierarchy) to focus after you update its value to be the empty string, `''`.
```javascript
varApp=React.createClass({
getInitialState:function(){
return{userInput:''};
},
handleKeyUp:function(e){
this.setState({userInput:e.target.value});
},
clearAndFocusInput:function(){
this.setState({userInput:''});// Clear the input
// We wish to focus the <input /> now!
},
render:function(){
return(
<div>
<divonClick={this.clearAndFocusInput}>
ClickToFocusandReset
</div>
<input
value={this.state.userInput}
onKeyUp={this.handleKeyUp}
/>
</div>
);
}
});
```
Notice how, in this example, we want to "tell" the input something - something that it cannot infer from its props over time. In this case we want to "tell" it that it should now become focused. However, there are some challenges. What is returned from `render()` is not your actual composition of "child" components, it is merely a *description* of the children at a particular instance in time - a snapshot, if you will.
> Note:
>
> Remember, what you return from `render()` is not your *actual* rendered children instances. What you return from `render()` is merely a *description* of the children instances in your component's sub-hierarchy at a particular moment in time.
This means that you should never "hold onto" something that you return from `render()` and then expect it to be anything meaningful.
```javascript
// counterexample: DO NOT DO THIS!
render:function(){
varmyInput=<input/>;// I'm going to try to call methods on this
this.rememberThisInput=myInput;// input at some point in the future! YAY!
return(
<div>
<div>...</div>
{myInput}
</div>
);
}
```
In this counterexample, the `<input />` is merely a *description* of an `<input />`. This description is used to create a *real***backing instance** for the `<input />`.
So how do we talk to the *real* backing instance of the input?
## The ref Attribute
React supports a very special property that you can attach to any component that is output from `render()`. This special property allows you to refer to the corresponding **backing instance** of anything returned from `render()`. It is always guaranteed to be the proper instance, at any point in time.
It's as simple as:
**1.** Assign a `ref` attribute to anything returned from `render` such as:
```html
<inputref="myInput"/>
```
**2.** In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
In this example, our render function returns a description of an `<input />` instance. But the true instance is accessed via `this.refs.theInput`. As long as a child component with `ref="theInput"` is returned from render, `this.refs.theInput` will access the proper instance. This even works on higher level (non-DOM) components such as `<Typeahead ref="myTypeahead" />`.
## Summary
Refs are a great way to send a message to a particular child instance in a way that would be inconvenient to do via streaming Reactive `props` and `state`. They should, however, not be your go-to abstraction for flowing data through your application. By default, use the Reactive data flow and save `ref`s for use cases that are inherently non-reactive.
### Benefits:
- You can define any public method on your component classes (such as a reset method on a Typeahead) and call those public methods through refs (such as `this.refs.myTypeahead.reset()`).
- Performing DOM measurements almost always requires reaching out to a "native" component such as `<input />` and accessing its underlying DOM node via `this.refs.myInput.getDOMNode()`. Refs are one of the only practical ways of doing this reliably.
- Refs are automatically book-kept for you! If that child is destroyed, its ref is also destroyed for you. No worrying about memory here (unless you do something crazy to retain a reference yourself).
### Cautions:
- *Never* access refs inside of any component's render method - or while any component's render method is even running anywhere in the call stack.
- If you want to preserve Google Closure Compiler Crushing resilience, make sure to never access as a property what was specified as a string. This means you must access using `this.refs['myRefString']` if your ref was defined as `ref="myRefString"`.
- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" - instead, the data flow will usually accomplish your goal.
Every project uses a different system for building and deploying JavaScript. We've tried to make React as environment-agnostic as possible.
## React
### CDN-hosted React
We provide CDN-hosted versions of React [on our download page](/react/downloads.html). These prebuilt files use the UMD module format. Dropping them in with a simple `<script>` tag will inject a `React` global into your environment. It should also work out-of-the-box in CommonJS and AMD environments.
### Using master
We have instructions for building from `master` [in our GitHub repository](https://github.com/facebook/react). We build a tree of CommonJS modules under `build/modules` which you can drop into any environment or packaging tool that supports CommonJS.
## JSX
### In-browser JSX Transform
If you like using JSX, we provide an in-browser JSX transformer for development [on our download page](/react/downloads.html). Simply include a `<script type="text/jsx">` tag to engage the JSX transformer. Be sure to include the `/** @jsx React.DOM */` comment as well, otherwise the transformer will not run the transforms.
> Note:
>
> The in-browser JSX transformer is fairly large and results in extraneous computation client-side that can be avoided. Do not use it in production — see the next section.
### Productionizing: Precompiled JSX
If you have [npm](http://npmjs.org/), you can simply run `npm install -g react-tools` to install our command-line `jsx` tool. This tool will translate files that use JSX syntax to plain JavaScript files that can run directly in the browser. It will also watch directories for you and automatically transform files when they are changed; for example: `jsx --watch src/ build/`. Run `jsx --help` for more information on how to use this tool.
### Helpful Open-Source Projects
The open-source community has built tools that integrate JSX with several build systems. See [JSX integrations](/react/docs/complementary-tools.html#jsx-integrations) for the full list.
### Syntax Highlighting & Linting
* Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
* [JSX syntax highlighting](https://github.com/yungsters/sublime/blob/master/tmLanguage/JavaScript%20(JSX\).tmLanguage) is available for Sublime Text and other editors
that support `*.tmLanguage`.
* [web-mode.el](http://web-mode.org) is an autonomous emacs major mode that indents and highlights JSX
* Linting provides accurate line numbers after compiling without sourcemaps.
* Elements use standard scoping so linters can find usage of out-of-scope components.
### Debugging
[React Developer Tools](https://github.com/facebook/react-devtools) is a [Chrome extension](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en) that allows you to inspect the React component hierarchy in the Chrome Developer Tools.
`React.addons` is where we park some useful utilities for building React apps. **These should be considered experimental** but will eventually be rolled into core or a blessed utilities library:
- [`ReactTransitions`](animation.html), for dealing with animations and transitions that are usually not simple to implement, such as before a component's removal.
- [`ReactLink`](two-way-binding-helpers.html), to simplify the coordination between user's form input data and and the component's state.
- [`classSet()`](class-name-manipulation.html), for manipulating the DOM `class` string a bit more cleanly.
- [`ReactTestUtils`](test-utils.html), simple helpers for writing test cases (unminified build only).
- [`cloneWithProps()`](clone-with-props.html), to make shallow copies of React components and change their props.
- [`update()`](update.html), a helper function that makes dealing with immutable data in JavaScript easier.
To get the add-ons, use `react-with-addons.js` (and its minified counterpart) rather than the common `react.js`.
React provides a `ReactTransitionGroup` addon component as a low-level API for animation, and a `ReactCSSTransitionGroup` for easily implementing basic CSS animations and transitions.
## High-level API: `ReactCSSTransitionGroup`
`ReactCSSTransitionGroup` is based on `ReactTransitionGroup` and is an easy way to perform CSS transitions and animations when a React component enters or leaves the DOM. It's inspired by the excellent [ng-animate](http://www.nganimate.org/) library.
### Getting Started
`ReactCSSTransitionGroup` is the interface to `ReactTransitions`. This is a simple element that wraps all of the components you are interested in animating. Here's an example where we fade list items in and out.
```javascript{22-24}
/** @jsx React.DOM */
var ReactCSSTransitionGroup = React.addons.CSSTransitionGroup;
In this component, when a new item is added to `ReactCSSTransitionGroup` it will get the `example-enter` CSS class and the `example-enter-active` CSS class added in the next tick. This is a convention based on the `transitionName` prop.
You can use these classes to trigger a CSS animation or transition. For example, try adding this CSS and adding a new list item:
```css
.example-enter {
opacity: 0.01;
transition: opacity .5s ease-in;
}
.example-enter.example-enter-active {
opacity: 1;
}
```
You'll notice that when you try to remove an item `ReactCSSTransitionGroup` keeps it in the DOM. If you're using an unminified build of React with add-ons you'll see a warning that React was expecting an animation or transition to occur. That's because `ReactCSSTransitionGroup` keeps your DOM elements on the page until the animation completes. Try adding this CSS:
```css
.example-leave {
opacity: 1;
transition: opacity .5s ease-in;
}
.example-leave.example-leave-active {
opacity: 0.01;
}
```
### Disabling Animations
You can disable animating `enter` or `leave` animations if you want. For example, sometimes you may want an `enter` animation and no `leave` animation, but `ReactCSSTransitionGroup` waits for an animation to complete before removing your DOM node. You can add `transitionEnter={false}` or `transitionLeave={false}` props to `ReactCSSTransitionGroup` to disable these animations.
## Low-level API: `ReactTransitionGroup`
`ReactTransitionGroup` is the basis for animations. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.
### `componentWillEnter(callback)`
This is called at the same time as `componentDidMount()` for components added to an existing `TransitionGroup`. It will block other animations from occurring until `callback` is called. It will not be called on the initial render of a `TransitionGroup`.
### `componentDidEnter()`
This is called after the `callback` function that was passed to `componentWillEnter` is called.
### `componentWillLeave(callback)`
This is called when the child has been removed from the `ReactTransitionGroup`. Though the child has been removed, `ReactTransitionGroup` will keep it in the DOM until `callback` is called.
### `componentDidLeave()`
This is called when the `willLeave` `callback` is called (at the same time as `componentWillUnmount`).
### Rendering a Different Component
By default `ReactTransitionGroup` renders as a `span`. You can change this behavior by providing a `component` prop. For example, here's how you would render a `<ul>`:
```javascript{1}
<ReactTransitionGroup component={React.DOM.ul}>
...
</ReactTransitionGroup>
```
Every DOM component is under `React.DOM`. However, `component` does not need to be a DOM component. It can be any React component you want; even ones you've written yourself!
`ReactLink` is an easy way to express two-way binding with React.
> Note:
>
> If you're new to the framework, note that `ReactLink` is not needed for most applications and should be used cautiously.
In React, data flows one way: from owner to child. This is because data only flows one direction in [the Von Neumann model of computing](http://en.wikipedia.org/wiki/Von_Neumann_architecture). You can think of it as "one-way data binding."
However, there are lots of applications that require you to read some data and flow it back into your program. For example, when developing forms, you'll often want to update some React `state` when you receive user input. Or perhaps you want to perform layout in JavaScript and react to changes in some DOM element size.
In React, you would implement this by listening to a "change" event, read from your data source (usually the DOM) and call `setState()` on one of your components. "Closing the data flow loop" explicitly leads to more understandable and easier-to-maintain programs. See [our forms documentation](/react/docs/forms.html) for more information.
Two-way binding -- implicitly enforcing that some value in the DOM is always consistent with some React `state` -- is concise and supports a wide variety of applications. We've provided `ReactLink`: syntactic sugar for setting up the common data flow loop pattern described above, or "linking" some data source to React `state`.
> Note:
>
> ReactLink is just a thin wrapper and convention around the `onChange`/`setState()` pattern. It doesn't fundamentally change how data flows in your React application.
## ReactLink: Before and After
Here's a simple form example without using `ReactLink`:
This works really well and it's very clear how data is flowing, however with a lot of form fields it could get a bit verbose. Let's use `ReactLink` to save us some typing:
`LinkedStateMixin` adds a method to your React component called `linkState()`. `linkState()` returns a `ReactLink` object which contains the current value of the React state and a callback to change it.
`ReactLink` objects can be passed up and down the tree as props, so it's easy (and explicit) to set up two-way binding between a component deep in the hierarchy and state that lives higher in the hierarchy.
Note that `<input>` supports ReactLink for both `value` and `checked`.
## Under the Hood
There are two sides to `ReactLink`: the place where you create the `ReactLink` instance and the place where you use it. To prove how simple `ReactLink` is, let's rewrite each side separately to be more explicit.
As you can see, `ReactLink` objects are very simple objects that just have a `value` and `requestChange` prop. And `LinkedStateMixin` is similarly simple: it just populates those fields with a value from `this.state` and a callback that calls `this.setState()`.
The `valueLink` prop is also quite simple. It simply handles the `onChange` event and calls `this.props.valueLink.requestChange()` and also uses `this.props.valueLink.value` instead of `this.props.value`. That's it!
When using `classSet()`, pass an object with keys of the CSS class names you might or might not need. Truthy values will result in the key being a part of the resulting string.
`React.addons.TestUtils` makes it easy to test React components in the testing framework of your choice (we use [Jasmine](http://pivotal.github.io/jasmine/) with [jsdom](https://github.com/tmpvar/jsdom)).
Simulate an event dispatch on a React component instance or browser DOM node with optional `eventData` event data. **This is possibly the single most useful utility in `ReactTestUtils`.**
Pass a mocked component module to this method to augment it with useful methods that allow it to be used as a dummy React component. Instead of rendering as usual, the component will become a simple `<div>` (or other tag if `mockTagName` is provided) containing any provided children.
Traverse all components in `tree` and accumulate all components where `test(component)` is true. This is not that useful on its own, but it's used as a primitive for other test utils.
Like `scryRenderedDOMComponentsWithClass()` but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one.
Like `scryRenderedDOMComponentsWithTag()` but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one.
Same as `scryRenderedComponentsWithType()` but expects there to be one result and returns that one result, or throws exception if there is any other number of matches besides one.
In rare situations a component may want to change the props of a component that it doesn't own (like changing the `className` of a component passed as `this.props.children`). Other times it may want to make multiple copies of a component passed to it. `cloneWithProps()` makes this possible.
Do a shallow copy of `component` and merge any props provided by `extraProps`. Props are merged in the same manner as [`transferPropsTo()`](/react/docs/component-api.html#transferpropsto), so props like `className` will be merged intelligently.
React lets you use whatever style of data management you want, including mutation. However, if you can use immutable data in performance-critical parts of your application it's easy to implement a fast `shouldComponentUpdate()` method to significantly speed up your app.
Dealing with immutable data in JavaScript is more difficult than in languages designed for it, like [Clojure](http://clojure.org/). However, we've provided a simple immutability helper, `update()`, that makes dealing with this type of data much easier, *without* fundamentally changing how your data is represented.
## The main idea
If you mutate data like this:
```javascript
myData.x.y.z=7;
myData.a.b.push(9);
```
you have no way of determining which data has changed since the previous copy is destroyed. Instead, you need to create a new copy of `myData` and change only the parts of it that need to be changed. Then you can compare the old copy of `myData` with the new one in `shouldComponentUpdate()` using triple-equals:
```javascript
varnewData=deepCopy(myData);
newData.x.y.z=7;
newData.a.b.push(9);
```
Unfortunately, deep copies are expensive, and sometimes impossible. You can alleviate this by only copying objects that need to be changed and by reusing the objects that haven't changed. Unfortunately, in today's JavaScript this can be cumbersome:
```javascript
varnewData=extend(myData,{
x:extend(myData.x,{
y:extend(myData.x.y,{z:7}),
}),
a:extend(myData.a,{b:myData.a.b.concat(9)})
});
```
While this is fairly performant (since it only shallow copies `log n` objects and reuses the rest), it's a big pain to write. Look at all the repetition! This is not only annoying, but also provides a large surface area for bugs.
`update()` provides simple syntactic sugar around this pattern to make writing this code easier. This code becomes:
```javascript
varnewData=React.addons.update(myData,{
x:{y:{z:{$set:7}}},
a:{b:{$push:[7]}}
});
```
While the syntax takes a little getting used to (though it's inspired by [MongoDB's query language](http://docs.mongodb.org/manual/core/crud-introduction/#query)) there's no redundancy, it's statically analyzable and it's not much more typing than the mutative version.
The `$`-prefixed keys are called *directives*. The data structure they are "mutating" is called the *target*.
## Available directives
*`{$push: array}``push()` all the items in `array` on the target
*`{$unshift: array}``unshift()` all the items in `array` on the target
*`{$splice: array of arrays}` for each item in `array()` call `splice()` on the target with the parameters provided by the item.
*`{$set: any}` replace the target entirely
*`{$merge: object}` merge the keys of `object` with the target
`React` is the entry point to the React framework. If you're using one of the prebuilt packages it's available as a global; if you're using CommonJS modules you can `require()` it.
#### React.DOM
`React.DOM` provides all of the standard HTML tags needed to build a React app. You generally don't use it directly; instead, just include it as part of the `/** @jsx React.DOM */` docblock.
#### React.initializeTouchEvents
```javascript
initializeTouchEvents(booleanshouldUseTouch)
```
Configure React's event system to handle touch events on mobile devices.
#### React.autoBind
```javascript
functionautoBind(functionmethod)
```
Marks the provided function to be automatically bound to each React component instance created. This allows React components to define automatically bound methods and ensure that when called they will always reference their current instance.
Example:
```javascript
React.createClass({
click:React.autoBind(function(evt){
this.setState({jumping:true});
}),
render:function(){
// Look: no bind!
return<aonClick={this.click}>Jump</a>;
}
});
```
#### React.createClass
```javascript
functioncreateClass(objectspecification)
```
Creates a component given a specification. A component implements a `render` method which returns a single child. That child may have an arbitrarily deep child structure. One thing that makes components different than a standard prototypal classes is that you don't need to call new on them. They are convenience wrappers that construct backing instances (via new) for you.
Renders a React component into the DOM in the supplied `container`.
If the React component was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component.
## AbstractEvent
Your event handlers will be passed instances of `AbstractEvent`, a cross-browser wrapper around the browser's native event. It has the same interface as the browser's native event (such as `stopPropagation()` and `preventDefault()`) except they work exactly the same across all browsers.
If you find that you need the underlying browser event for some reason, simply use the `nativeEvent` attribute to get it.
## ReactComponent
Component classses created by `createClass()` return instances of `ReactComponent` when called. Most of the time when you're using React you're either creating or consuming `ReactComponent`s.
#### getDOMNode
```javascript
DOMElementgetDOMNode()
```
If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements.
#### setProps
```javascript
setProps(objectnextProps)
```
When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `renderComponent()`. Simply call `setProps()` to change its properties and trigger a re-render.
**Note:** This method can only be called on a root-level component. That is, it's only available on the component passed directly to `renderComponent()` and none of its children. If you're inclined to use `setProps()` on a child component, instead take advantage of reactive updates and pass the new prop to the child component when it's created in `render()`.
#### replaceProps
```javascript
replaceProps(objectnextProps)
```
Like `setProps()` but deletes any pre-existing props that are not in nextProps.
Transfer properties from this component to a target component that have not already been set on the target component. This is usually used to pass down properties to the returned root component. `targetComponent`, now updated with some new props is returned as a convenience.
#### setState
```javascript
setState(objectnextState)
```
Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks.
**Note:***NEVER* mutate `this.state` directly. As calling `setState()` afterwards may replace the mutation you made. Treat `this.state` as if it were immutable.
**Note:**`setState()` does not immediately mutate `this.state` but creates a pending state transition. Accessing `this.state` after calling this method can potentially return the existing value.
#### replaceState
```javascript
replaceState(objectnextState)
```
Like `setState()` but deletes any pre-existing state keys that are not in nextState.
#### forceUpdate()
```javascript
forceUpdate()
```
If your `render()` method reads from something other than `this.props` or `this.state` you'll need to tell React when it needs to re-run `render()`. Use `forceUpdate()` to cause React to automatically re-render. This will cause `render()` to be called on the component and all of its children but React will only update the DOM if the markup changes.
Normally you should try to avoid all uses of `forceUpdate()` and only read from `this.props` and `this.state` in `render()`. This makes your application much simpler and more efficient.
React supports the latest two Chrome, Firefox, Safari, and Internet Explorer versions. React can work with Internet Explorer 8 with polyfills.
### How do I get React to support Internet Explorer 8?
React requires ES5 JavaScript shims to run in Internet Explorer 8. Include the [ES5 Shims](https://github.com/kriskowal/es5-shim) to implement these shims.
### Who uses React?
The [Instagram](http://instagram.com/) website is built entirely in React. The [Facebook](https://www.facebook.com/) website is also increasingly using React, including the common commenting plugin across the site.
### I don't get it. React is confusing!
[This blog post by a member of the React team](http://www.quora.com/Pete-Hunt/Posts/React-Under-the-Hood) talks about some of the reasons
why React is designed the way that it is.
### Can I integrate with other JavaScript libraries?
Absolutely! In fact, we encourage it! See [our GitHub repo](http://github.com/facebook/react/) for a [TodoMVC example using Backbone](https://github.com/facebook/react/tree/master/examples/todomvc-backbone) and a [jQuery + Bootstrap modal demo](https://github.com/facebook/react/tree/master/examples/jquery-bootstrap).
React is a small library that does one thing well. Here's a list of tools we've found that work really well with React when building applications.
If you want your project on this list, or think one of these projects should be removed, [open an issue on GitHub](https://github.com/facebook/react/issues/new).
* **[pyReact](https://github.com/facebook/react-python)** [Python](http://www.python.org/) bridge to JSX.
* **[react-rails](https://github.com/facebook/react-rails)** Ruby gem for using JSX with [Ruby on Rails](http://rubyonrails.org/).
### Full-stack starter kits
* **[react-quickstart](https://github.com/andreypopp/react-quickstart)** Quick-start template for `express`, `browserify`, `react-router-component` and `react-async` (**includes "isomorphic" server rendering**).
* **[generator-react-webpack](https://github.com/newtriks/generator-react-webpack)** [Yeoman](http://yeoman.io/) generator for React and Webpack.
* **[Genesis Skeleton](http://genesis-skeleton.com/)** Modern, opinionated, full-stack starter kit for rapid, streamlined application development (supports React).
* **[react-starter-template](https://github.com/johnthethird/react-starter-template)** Starter template with Gulp, Webpack and Bootstrap.
* **[react-browserify-template](https://github.com/petehunt/react-browserify-template)** Quick-start with Browserify.
### Routing
* **[director](https://github.com/flatiron/director)** (For an example see [TodoMVC](https://github.com/tastejs/todomvc/blob/gh-pages/architecture-examples/react/js/app.jsx#L29)).
* **[Backbone](http://backbonejs.org/)** (For an example see [github-issues-viewer](https://github.com/jaredly/github-issues-viewer)).
* **[react.backbone](https://github.com/usepropeller/react.backbone)** Use [Backbone](http://backbonejs.org) models with React.
* **[cortex](https://github.com/mquan/cortex/)** A JavaScript library for centrally managing data with React.
* **[avers](https://github.com/wereHamster/avers)** A modern client-side model abstraction library.
### Data fetching
* **[react-async](http://andreypopp.viewdocs.io/react-async)** Adds a `getInitialStateAsync(cb)` method suitable for data fetching on both the client and the server.
* **[superagent](http://visionmedia.github.io/superagent/)** A lightweight "isomorphic" library for AJAX requests.
### UI components
* **[react-bootstrap](https://github.com/stevoland/react-bootstrap)** Bootstrap 3 components built with React.
* **[react-topcoat](https://github.com/plaxdan/react-topcoat)** Topcoat components built with React.
* **[react-lorem-component](https://github.com/martinandert/react-lorem-component)** Lorem Ipsum placeholder component.
* **[wingspan-forms](https://github.com/wingspan/wingspan-forms)** React library for dynamic forms & grids; widgets provided by KendoUI.
* **[react-translate-component](https://github.com/martinandert/react-translate-component)** React component for i18n.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
