diff --git a/docs/02-displaying-data.md b/docs/02-displaying-data.md
index 1305293c..719bb750 100644
--- a/docs/02-displaying-data.md
+++ b/docs/02-displaying-data.md
@@ -8,7 +8,6 @@ next: jsx-in-depth.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:
@@ -56,7 +55,6 @@ setInterval(function() {
}, 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.
@@ -65,7 +63,6 @@ The way we are able to figure this out is that React does not manipulate the DOM
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 functions that take in `props` and `state` (discussed later) and render HTML. With this in mind, components are easy to reason about.
@@ -74,7 +71,6 @@ React components are very simple. You can think of them as simple functions that
>
> **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.
@@ -99,7 +95,6 @@ JSX is similar to HTML, but not exactly the same. See [JSX gotchas](/react/docs/
[Babel exposes a number of ways to get started using JSX](http://babeljs.io/docs/setup/), ranging from command line tools to Ruby on Rails integrations. Choose the tool that works best for you.
-
## React without JSX
JSX is completely optional; you don't have to use JSX with React. You can create React elements in plain JavaScript using `React.createElement`, which takes a tag name or component, a properties object, and variable number of optional child arguments.
diff --git a/docs/02.2-jsx-spread.md b/docs/02.2-jsx-spread.md
index 4b6f4659..4cafa8cc 100644
--- a/docs/02.2-jsx-spread.md
+++ b/docs/02.2-jsx-spread.md
@@ -12,7 +12,7 @@ If you know all the properties that you want to place on a component ahead of ti
var component = ;
```
-## Mutating Props is Bad, mkay
+## Mutating Props is Bad
If you don't know which properties you want to set, you might be tempted to add them onto the object later:
diff --git a/docs/02.3-jsx-gotchas.md b/docs/02.3-jsx-gotchas.md
index 88a16d74..6ab5d4ad 100644
--- a/docs/02.3-jsx-gotchas.md
+++ b/docs/02.3-jsx-gotchas.md
@@ -27,7 +27,7 @@ If you want to display an HTML entity within dynamic content, you will run into
{'First · Second'}
```
-There are various ways to work-around this issue. The easiest one is to write unicode characters 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.
+There are various ways to work-around this issue. The easiest one is to write Unicode characters 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
{'First · Second'}
diff --git a/docs/03-interactivity-and-dynamic-uis.md b/docs/03-interactivity-and-dynamic-uis.md
index f26307e4..f5f82c93 100644
--- a/docs/03-interactivity-and-dynamic-uis.md
+++ b/docs/03-interactivity-and-dynamic-uis.md
@@ -8,7 +8,6 @@ next: multiple-components.html
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
@@ -35,12 +34,10 @@ ReactDOM.render(
);
```
-
## 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.
-
## Under the Hood: Autobinding and Event Delegation
Under the hood, React does a few things to keep your code performant and easy to understand.
@@ -49,19 +46,16 @@ Under the hood, React does a few things to keep your code performant and easy to
**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.
@@ -70,12 +64,11 @@ Most of your components should simply take some data from `props` and render it.
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?
+## 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:
diff --git a/docs/04-multiple-components.md b/docs/04-multiple-components.md
index 03cd8077..f6fa1de1 100644
--- a/docs/04-multiple-components.md
+++ b/docs/04-multiple-components.md
@@ -8,12 +8,10 @@ next: reusable-components.html
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.
@@ -54,14 +52,12 @@ ReactDOM.render(
);
```
-
## Ownership
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 fundamental invariant 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:
@@ -72,7 +68,6 @@ When you create a React component instance, you can include additional React com
`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:
@@ -91,7 +86,6 @@ When you create a React component instance, you can include additional React com
Intuitively, `
Paragraph 1
` 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.
@@ -111,7 +105,6 @@ In most cases, this can be sidestepped by hiding elements instead of destroying
```
-
### 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`:
@@ -178,7 +171,6 @@ You can also key children by passing a ReactFragment object. See [Keyed Fragment
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 change 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. React will optimize this for you by using batching and change detection.
diff --git a/docs/05-reusable-components.md b/docs/05-reusable-components.md
index 55acbbc7..75e23858 100644
--- a/docs/05-reusable-components.md
+++ b/docs/05-reusable-components.md
@@ -8,7 +8,6 @@ next: transferring-props.html
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. This means faster development time, fewer bugs, and fewer 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:
@@ -79,7 +78,6 @@ React.createClass({
});
```
-
## Default Prop Values
React lets you define default values for your `props` in a very declarative way:
@@ -97,7 +95,6 @@ var ComponentWithDefaultProps = React.createClass({
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 element 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, you can use the JSX _spread_ syntax to achieve this:
@@ -233,8 +230,6 @@ Methods follow the same semantics as regular ES6 classes, meaning that they don'
Unfortunately ES6 launched without any mixin support. Therefore, there is no support for mixins when you use React with ES6 classes. Instead, we're working on making it easier to support such use cases without resorting to mixins.
-
-
## Stateless Functions
You may also define your React classes as a plain JavaScript function. For example using the stateless function syntax:
@@ -253,7 +248,6 @@ var HelloMessage = (props) =>
Hello {props.name}
;
ReactDOM.render(, mountNode);
```
-
This simplified component API is intended for components that are pure functions of their props. These components must not retain internal state, do not have backing instances, and do not have the component lifecycle methods. They are pure functional transforms of their input, with zero boilerplate.
> NOTE:
@@ -261,4 +255,3 @@ This simplified component API is intended for components that are pure functions
> Because stateless functions don't have a backing instance, you can't attach a ref to a stateless function component. Normally this isn't an issue, since stateless functions do not provide an imperative API. Without an imperative API, there isn't much you could do with an instance anyway. However, if a user wants to find the DOM node of a stateless function component, they must wrap the component in a stateful component (eg. ES6 class component) and attach the ref to the stateful wrapper component.
In an ideal world, most of your components would be stateless functions because these stateless components can follow a faster code path within the React core. This is the recommended pattern, when possible.
-
diff --git a/docs/07-forms.md b/docs/07-forms.md
index ba8e07ee..af75d4b2 100644
--- a/docs/07-forms.md
+++ b/docs/07-forms.md
@@ -32,7 +32,6 @@ Like all DOM events, the `onChange` prop is supported on all native components a
>
> For `` and `