React
Edit on GitHub

React Top-Level API

React is the entry point to the React library. If you use React as a script tag, these top-level APIs are available on the React global. If you use ES6 with npm, you can write import React from 'react'. If you use ES5 with npm, you can write var React = require('react').

Overview #

Components #

React components let you split the UI into independent, reusable pieces, and think about each piece in isolation. React components can be defined by subclassing React.Component or React.PureComponent.

If you don't use ES6 classes, you may use this helper instead.

Creating React Elements #

We recommend using JSX to describe what your UI should look like. Each JSX element is just syntactic sugar for calling React.createElement(). You will not typically invoke the following methods directly if you are using JSX.

See Using React without JSX for more information.

Transforming Elements #

React also provides some other APIs:

Typechecking with PropTypes #

You can use React.PropTypes to run typechecking on the props for a component.

Validators treat props as optional by default. You can use isRequired to make sure a warning is shown if the prop is not provided.

Add-Ons #

If you're using react-with-addons.js, the React Add-Ons will be available via React.addons.

Reference #

React.Component #

React.Component is the base class for React components when they are defined using ES6 classes.

class Greeting extends React.Component {
  render() {
    return <h1>Hello, {this.props.name}</h1>;
  }
}

See the React.Component API Reference for a list of methods and properties related to the base React.Component class.

React.PureComponent #

React.PureComponent is exactly like React.Component but implements shouldComponentUpdate() with a shallow prop and state comparison.

If your React component's render() function renders the same result given the same props and state, you can use React.PureComponent for a performance boost in some cases.

Note

React.PureComponent's shouldComponentUpdate() only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only extend PureComponent when you expect to have simple props and state, or use forceUpdate() when you know deep data structures have changed. Or, consider using immutable objects to facilitate fast comparisons of nested data.

Furthermore, React.PureComponent's shouldComponentUpdate() skips prop updates for the whole component subtree. Make sure all the children components are also "pure".

createClass() #

React.createClass(specification)

If you don't use ES6 yet, you may use the React.createClass() helper instead to create a component class.

var Greeting = React.createClass({
  render: function() {
    return <h1>Hello, {this.props.name}</h1>;
  }
});

See Using React without ES6 for more information.

createElement() #

React.createElement(
  type,
  [props],
  [...children]
)

Create and return a new React element of the given type. The type argument can be either a tag name string (such as 'div' or 'span'), or a React component type (a class or a function).

Convenience wrappers around React.createElement() for DOM components are provided by React.DOM. For example, React.DOM.a(...) is a convenience wrapper for React.createElement('a', ...). They are considered legacy, and we encourage you to either use JSX or use React.createElement() directly instead.

Code written with JSX will be converted to use React.createElement(). You will not typically invoke React.createElement() directly if you are using JSX. See React Without JSX to learn more.

cloneElement() #

React.cloneElement(
  element,
  [props],
  [...children]
)

Clone and return a new React element using element as the starting point. The resulting element will have the original element's props with the new props merged in shallowly. New children will replace existing children. key and ref from the original element will be preserved.

React.cloneElement() is almost equivalent to:

<element.type {...element.props} {...props}>{children}</element.type>

However, it also preserves refs. This means that if you get a child with a ref on it, you won't accidentally steal it from your ancestor. You will get the same ref attached to your new element.

This API was introduced as a replacement of the deprecated React.addons.cloneWithProps().

createFactory() #

React.createFactory(type)

Return a function that produces React elements of a given type. Like React.createElement(), the type argument can be either a tag name string (such as 'div' or 'span'), or a React component type (a class or a function).

This helper is considered legacy, and we encourage you to either use JSX or use React.createElement() directly instead.

You will not typically invoke React.createFactory() directly if you are using JSX. See React Without JSX to learn more.

isValidElement() #

React.isValidElement(object)

Verifies the object is a React element. Returns true or false.

React.Children #

React.Children provides utilities for dealing with the this.props.children opaque data structure.

React.Children.map #

React.Children.map(children, function[(thisArg)])

Invokes a function on every immediate child contained within children with this set to thisArg. If children is a keyed fragment or array it will be traversed: the function will never be passed the container objects. If children is null or undefined, returns null or undefined rather than an array.

React.Children.forEach #

React.Children.forEach(children, function[(thisArg)])

Like React.Children.map() but does not return an array.

React.Children.count #

React.Children.count(children)

Returns the total number of components in children, equal to the number of times that a callback passed to map or forEach would be invoked.

React.Children.only #

React.Children.only(children)

Returns the only child in children. Throws otherwise.

React.Children.toArray #

React.Children.toArray(children)

Returns the children opaque data structure as a flat array with keys assigned to each child. Useful if you want to manipulate collections of children in your render methods, especially if you want to reorder or slice this.props.children before passing it down.

Note:

React.Children.toArray() changes keys to preserve the semantics of nested arrays when flattening lists of children. That is, toArray prefixes each key in the returned array so that each element's key is scoped to the input array containing it.

React.PropTypes #

React.PropTypes exports a range of validators that can be used with a component's propTypes object to validate props being passed to your components.

For more information about PropTypes, see Typechecking with PropTypes.

React.PropTypes.array #

React.PropTypes.array

Validates that a prop is a JavaScript array primitive.

React.PropTypes.bool #

React.PropTypes.bool

Validates that a prop is a JavaScript bool primitive.

React.PropTypes.func #

React.PropTypes.func

Validates that a prop is a JavaScript function.

React.PropTypes.number #

React.PropTypes.number

Validates that a prop is a JavaScript number primitive.

React.PropTypes.object #

React.PropTypes.object

Validates that a prop is a JavaScript object.

React.PropTypes.string #

React.PropTypes.string

Validates that a prop is a JavaScript string primitive.

React.PropTypes.symbol #

React.PropTypes.symbol

Validates that a prop is a JavaScript symbol.

React.PropTypes.node #

React.PropTypes.node

Validates that a prop is anything that can be rendered: numbers, strings, elements or an array (or fragment) containing these types.

React.PropTypes.element #

React.PropTypes.element

Validates that a prop is a React element.

React.PropTypes.instanceOf() #

React.PropTypes.instanceOf(class)

Validates that a prop is an instance of a class. This uses JavaScript's instanceof operator.

React.PropTypes.oneOf() #

React.PropTypes.oneOf(arrayOfValues)

Validates that a prop is limited to specific values by treating it as an enum.

MyComponent.propTypes = {
  optionalEnum: React.PropTypes.oneOf(['News', 'Photos']),
}

React.PropTypes.oneOfType() #

React.PropTypes.oneOfType(arrayOfPropTypes)

Validates that a prop is an object that could be one of many types.

MyComponent.propTypes = {
  optionalUnion: React.PropTypes.oneOfType([
    React.PropTypes.string,
    React.PropTypes.number,
    React.PropTypes.instanceOf(Message)
  ]),
}

React.PropTypes.arrayOf() #

React.PropTypes.arrayOf(propType)

Validates that a prop is an an array of a certain type.

MyComponent.propTypes = {
  optionalArrayOf: React.PropTypes.arrayOf(React.PropTypes.number),
}

React.PropTypes.objectOf() #

React.PropTypes.objectOf(propType)

Validates that a prop is an object with property values of a certain type.

MyComponent.propTypes = {
  optionalObjectOf: React.PropTypes.objectOf(React.PropTypes.number),
}

React.PropTypes.shape() #

React.PropTypes.shape(object)

Validates that a prop is an object taking on a particular shape.

MyComponent.propTypes = {
  optionalObjectWithShape: React.PropTypes.shape({
    color: React.PropTypes.string,
    fontSize: React.PropTypes.number
  }),
}

React.PropTypes.any #

React.PropTypes.any

Validates that a prop has a value of any data type. Usually followed by isRequired.

MyComponent.propTypes = {
  requiredAny: React.PropTypes.any.isRequired,
}

isRequired #

propType.isRequired

You can chain any of the above validators with isRequired to make sure a warning is shown if the prop is not provided.

MyComponent.propTypes = {
  requiredFunc: React.PropTypes.func.isRequired,
}

React.addons #

React.addons

React.addons exports a range of add-ons when using react-with-addons.js.

Quick Start

Advanced Guides

Reference

Contributing