React
is the entry point to the React library. If you load React from 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')
.
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 the create-react-class
module instead. See Using React without ES6 for more information.
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.
React
provides several APIs for manipulating elements:
React
also provides a component for rendering a multiple elements without a wrapper.
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 similar to React.Component
. The difference between them is that React.Component
doesn’t implement shouldComponentUpdate()
, but React.PureComponent
implements it 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
’sshouldComponentUpdate()
only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only extendPureComponent
when you expect to have simple props and state, or useforceUpdate()
when you know deep data structures have changed. Or, consider using immutable objects to facilitate fast comparisons of nested data.Furthermore,
React.PureComponent
’sshouldComponentUpdate()
skips prop updates for the whole component subtree. Make sure all the children components are also “pure”.
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'
), a React component type (a class or a function), or a React fragment type.
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 ref
s. 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'
), a React component type (a class or a function), or a React fragment type.
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)
Verifies that children
has only one child (a React element) and returns it. Otherwise this method throws an error.
Note:
React.Children.only()
does not accept the return value ofReact.Children.map()
because it is an array rather than a React element.
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.Fragment
The React.Fragment
component lets you return multiple elements in a render()
method without creating an additional DOM element:
render() { return ( <React.Fragment> Some text. <h2>A heading</h2> </React.Fragment> ); }
You can also use it with the shorthand <></>
syntax. For more information, see React v16.2.0: Improved Support for Fragments.
© 2013–present Facebook Inc.
Licensed under the Creative Commons Attribution 4.0 International Public License.
https://reactjs.org/docs/react-api.html