diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml index 1e66741d1fb24..ccf9a40acc689 100644 --- a/docs/_data/nav_docs.yml +++ b/docs/_data/nav_docs.yml @@ -30,8 +30,6 @@ items: - id: jsx-in-depth title: JSX In Depth - - id: typechecking-with-proptypes - title: Typechecking With PropTypes - id: refs-and-the-dom title: Refs and the DOM - id: uncontrolled-components diff --git a/docs/docs/addons-pure-render-mixin.md b/docs/docs/addons-pure-render-mixin.md index 86193c0371949..d4cafdc03441a 100644 --- a/docs/docs/addons-pure-render-mixin.md +++ b/docs/docs/addons-pure-render-mixin.md @@ -24,7 +24,9 @@ If your React component's render function renders the same result given the same Example: ```js -React.createClass({ +const createReactClass = require('create-react-class'); + +createReactClass({ mixins: [PureRenderMixin], render: function() { diff --git a/docs/docs/addons-two-way-binding-helpers.md b/docs/docs/addons-two-way-binding-helpers.md index 29e9662e93b6b..498c7bf08493f 100644 --- a/docs/docs/addons-two-way-binding-helpers.md +++ b/docs/docs/addons-two-way-binding-helpers.md @@ -40,7 +40,9 @@ Two-way binding -- implicitly enforcing that some value in the DOM is always con Here's a simple form example without using `LinkedStateMixin`: ```javascript -var NoLink = React.createClass({ +var createReactClass = require('create-react-class'); + +var NoLink = createReactClass({ getInitialState: function() { return {message: 'Hello!'}; }, @@ -57,7 +59,9 @@ var NoLink = React.createClass({ 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 `LinkedStateMixin` to save us some typing: ```javascript{4,9} -var WithLink = React.createClass({ +var createReactClass = require('create-react-class'); + +var WithLink = createReactClass({ mixins: [LinkedStateMixin], getInitialState: function() { return {message: 'Hello!'}; @@ -83,8 +87,10 @@ There are two sides to `LinkedStateMixin`: the place where you create the `value ### valueLink Without LinkedStateMixin -```javascript{5-7,9-12} -var WithoutMixin = React.createClass({ +```javascript{7-9,11-14} +var createReactClass = require('create-react-class'); + +var WithoutMixin = createReactClass({ getInitialState: function() { return {message: 'Hello!'}; }, @@ -107,8 +113,9 @@ As you can see, `valueLink` objects are very simple objects that just have a `va ```javascript var LinkedStateMixin = require('react-addons-linked-state-mixin'); +var createReactClass = require('create-react-class'); -var WithoutLink = React.createClass({ +var WithoutLink = createReactClass({ mixins: [LinkedStateMixin], getInitialState: function() { return {message: 'Hello!'}; diff --git a/docs/docs/context.md b/docs/docs/context.md index cfe86556f599d..e3efaf5d5b308 100644 --- a/docs/docs/context.md +++ b/docs/docs/context.md @@ -4,11 +4,15 @@ title: Context permalink: docs/context.html --- +>Note: +> As of React v15.5 the `React.PropTypes` helper is deprecated, and we recommend using the [`prop-types` library](https://github.com/aackerman/PropTypes) to define `contextTypes`. + With React, it's easy to track the flow of data through your React components. When you look at a component, you can see which props are being passed, which makes your apps easy to reason about. In some cases, you want to pass data through the component tree without having to pass the props down manually at every level. You can do this directly in React with the powerful "context" API. + ## Why Not To Use Context The vast majority of applications do not need to use context. @@ -59,7 +63,9 @@ class MessageList extends React.Component { In this example, we manually thread through a `color` prop in order to style the `Button` and `Message` components appropriately. Using context, we can pass this through the tree automatically: -```javascript{4,11-13,19,26-28,38-40} +```javascript{6,13-15,21,28-30,40-42} +const PropTypes = require('prop-types'); + class Button extends React.Component { render() { return ( @@ -71,7 +77,7 @@ class Button extends React.Component { } Button.contextTypes = { - color: React.PropTypes.string + color: PropTypes.string }; class Message extends React.Component { @@ -98,7 +104,7 @@ class MessageList extends React.Component { } MessageList.childContextTypes = { - color: React.PropTypes.string + color: PropTypes.string }; ``` @@ -151,12 +157,14 @@ If `contextTypes` is defined within a component, the following [lifecycle method Stateless functional components are also able to reference `context` if `contextTypes` is defined as a property of the function. The following code shows a `Button` component written as a stateless functional component. ```javascript +const PropTypes = require('prop-types'); + const Button = ({children}, context) => ; -Button.contextTypes = {color: React.PropTypes.string}; +Button.contextTypes = {color: PropTypes.string}; ``` ## Updating Context @@ -168,6 +176,8 @@ React has an API to update context, but it is fundamentally broken and you shoul The `getChildContext` function will be called when the state or props changes. In order to update data in the context, trigger a local state update with `this.setState`. This will trigger a new context and changes will be received by the children. ```javascript +const PropTypes = require('prop-types'); + class MediaQuery extends React.Component { constructor(props) { super(props); @@ -196,7 +206,7 @@ class MediaQuery extends React.Component { } MediaQuery.childContextTypes = { - type: React.PropTypes.string + type: PropTypes.string }; ``` diff --git a/docs/docs/react-without-es6.md b/docs/docs/react-without-es6.md index 84fa1fefe7f06..e49a5e0757088 100644 --- a/docs/docs/react-without-es6.md +++ b/docs/docs/react-without-es6.md @@ -14,45 +14,38 @@ class Greeting extends React.Component { } ``` -If you don't use ES6 yet, you may use the `React.createClass` helper instead: +If you don't use ES6 yet, you may use the `create-react-class` module instead: ```javascript -var Greeting = React.createClass({ +var createReactClass = require('create-react-class'); +var Greeting = createReactClass({ render: function() { return

Hello, {this.props.name}

; } }); ``` -The API of ES6 classes is similar to `React.createClass` with a few exceptions. +The API of ES6 classes is similar to `createReactClass()` with a few exceptions. -## Declaring Prop Types and Default Props +## Declaring Default Props -With functions and ES6 classes, `propTypes` and `defaultProps` are defined as properties on the components themselves: +With functions and ES6 classes `defaultProps` is defined as a property on the component itself: ```javascript class Greeting extends React.Component { // ... } -Greeting.propTypes = { - name: React.PropTypes.string -}; - Greeting.defaultProps = { name: 'Mary' }; ``` -With `React.createClass()`, you need to define `propTypes` as a property on the passed object, and `getDefaultProps()` as a function on it: +With `createReactClass()`, you need to define `getDefaultProps()` as a function on the passed object: ```javascript -var Greeting = React.createClass({ - propTypes: { - name: React.PropTypes.string - }, - +var Greeting = createReactClass({ getDefaultProps: function() { return { name: 'Mary' @@ -78,10 +71,10 @@ class Counter extends React.Component { } ``` -With `React.createClass()`, you have to provide a separate `getInitialState` method that returns the initial state: +With `createReactClass()`, you have to provide a separate `getInitialState` method that returns the initial state: ```javascript -var Counter = React.createClass({ +var Counter = createReactClass({ getInitialState: function() { return {count: this.props.initialCount}; }, @@ -117,14 +110,14 @@ class SayHello extends React.Component { } ``` -With `React.createClass()`, this is not necessary because it binds all methods: +With `createReactClass()`, this is not necessary because it binds all methods: ```javascript -var SayHello = React.createClass({ +var SayHello = createReactClass({ getInitialState: function() { return {message: 'Hello!'}; }, - + handleClick: function() { alert(this.state.message); }, @@ -172,7 +165,7 @@ If you'd rather play it safe, you have a few options: * Bind methods in the constructor. * Use arrow functions, e.g. `onClick={(e) => this.handleClick(e)}`. -* Keep using `React.createClass()`. +* Keep using `createReactClass`. ## Mixins @@ -184,7 +177,7 @@ If you'd rather play it safe, you have a few options: > >This section exists only for the reference. -Sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](https://en.wikipedia.org/wiki/Cross-cutting_concern). [`React.createClass`](/react/docs/top-level-api.html#react.createclass) lets you use a legacy `mixins` system for that. +Sometimes very different components may share some common functionality. These are sometimes called [cross-cutting concerns](https://en.wikipedia.org/wiki/Cross-cutting_concern). [`createReactClass`](/react/docs/top-level-api.html#react.createclass) lets you use a legacy `mixins` system for that. 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. @@ -201,7 +194,9 @@ var SetIntervalMixin = { } }; -var TickTock = React.createClass({ +var createReactClass = require('create-react-class'); + +var TickTock = createReactClass({ mixins: [SetIntervalMixin], // Use the mixin getInitialState: function() { return {seconds: 0}; diff --git a/docs/docs/reference-pure-render-mixin.md b/docs/docs/reference-pure-render-mixin.md index 4b2e5a439dbfd..cee8bcaa948bd 100644 --- a/docs/docs/reference-pure-render-mixin.md +++ b/docs/docs/reference-pure-render-mixin.md @@ -16,7 +16,8 @@ Example: ```js var PureRenderMixin = require('react-addons-pure-render-mixin'); -React.createClass({ +var createReactClass = require('create-react-class'); +createReactClass({ mixins: [PureRenderMixin], render: function() { diff --git a/docs/docs/reference-react-component.md b/docs/docs/reference-react-component.md index b274da6edf332..d8c2be7302fec 100644 --- a/docs/docs/reference-react-component.md +++ b/docs/docs/reference-react-component.md @@ -31,7 +31,7 @@ class Greeting extends React.Component { } ``` -If you don't use ES6 yet, you may use the [`React.createClass`](/react/docs/react-api.html#createclass) helper instead. Take a look at [Using React without ES6](/react/docs/react-without-es6.html) to learn more. +If you don't use ES6 yet, you may use the [`create-react-class`](/react/docs/react-api.html#createclass) module instead. Take a look at [Using React without ES6](/react/docs/react-without-es6.html) to learn more. ### The Component Lifecycle @@ -73,7 +73,6 @@ Each component also provides some other APIs: - [`defaultProps`](#defaultprops) - [`displayName`](#displayname) - - [`propTypes`](#proptypes) ### Instance Properties @@ -122,7 +121,7 @@ constructor(props) { this.state = { color: props.initialColor }; -} +} ``` Beware of this pattern, as it effectively "forks" the props and can lead to bugs. Instead of syncing props to state, you often want to [lift the state up](/react/docs/lifting-state-up.html). @@ -315,26 +314,6 @@ The `displayName` string is used in debugging messages. JSX sets this value auto * * * -### `propTypes` - -`propTypes` can be defined as a property on the component class itself, to define what types the props should be. It should be a map from prop names to types as defined in [`React.PropTypes`](/react/docs/react-api.html#react.proptypes). In development mode, when an invalid value is provided for a prop, a warning will be shown in the JavaScript console. In production mode, `propTypes` checks are skipped for efficiency. - -For example, this code ensures that the `color` prop is a string: - -```js -class CustomButton extends React.Component { - // ... -} - -CustomButton.propTypes = { - color: React.PropTypes.string -}; -``` - -We recommend using [Flow](https://flowtype.org/) when possible, to get compile-time typechecking instead of runtime typechecking. [Flow has built-in support for React](https://flowtype.org/docs/react.html) so it's easy to run static analysis on a React app. - -* * * - ## Instance Properties ### `props` diff --git a/docs/docs/reference-react.md b/docs/docs/reference-react.md index a00770a2fb5f9..23091681d891c 100644 --- a/docs/docs/reference-react.md +++ b/docs/docs/reference-react.md @@ -25,9 +25,7 @@ React components let you split the UI into independent, reusable pieces, and thi - [`React.Component`](#react.component) - [`React.PureComponent`](#react.purecomponent) -If you don't use ES6 classes, you may use this helper instead. - - - [`createClass()`](#createclass) +If you don't use ES6 classes, you may use the `create-react-class` module instead. See [Using React without ES6](/react/docs/react-without-es6.html) for more information. ### Creating React Elements @@ -46,32 +44,6 @@ See [Using React without JSX](/react/docs/react-without-jsx.html) for more infor - [`isValidElement()`](#isvalidelement) - [`React.Children`](#react.children) -### Typechecking with PropTypes - -You can use `React.PropTypes` to run typechecking on the props for a component. - - - [`React.PropTypes`](#react.proptypes) - - [`React.PropTypes.array`](#react.proptypes.array) - - [`React.PropTypes.bool`](#react.proptypes.bool) - - [`React.PropTypes.func`](#react.proptypes.func) - - [`React.PropTypes.number`](#react.proptypes.number) - - [`React.PropTypes.object`](#react.proptypes.object) - - [`React.PropTypes.string`](#react.proptypes.string) - - [`React.PropTypes.symbol`](#react.proptypes.symbol) - - [`React.PropTypes.node`](#react.proptypes.node) - - [`React.PropTypes.element`](#react.proptypes.element) - - [`React.PropTypes.instanceOf()`](#react.proptypes.instanceof) - - [`React.PropTypes.oneOf()`](#react.proptypes.oneof) - - [`React.PropTypes.oneOfType()`](#react.proptypes.oneoftype) - - [`React.PropTypes.arrayOf()`](#react.proptypes.arrayof) - - [`React.PropTypes.objectOf()`](#react.proptypes.objectof) - - [`React.PropTypes.shape()`](#react.proptypes.shape) - - [`React.PropTypes.any`](#react.proptypes.any) - -Validators treat props as optional by default. You can use `isRequired` to make sure a warning is shown if the prop is not provided. - - - [`isRequired`](#isrequired) - ### Add-Ons If you're using [`react-with-addons.js`](/react/docs/addons.html), the React Add-Ons will be available via `React.addons`. @@ -112,26 +84,6 @@ If your React component's `render()` function renders the same result given the * * * -### `createClass()` - -```javascript -React.createClass(specification) -``` - -If you don't use ES6 yet, you may use the `React.createClass()` helper instead to create a component class. - -```javascript -var Greeting = React.createClass({ - render: function() { - return

Hello, {this.props.name}

; - } -}); -``` - -See [Using React without ES6](/react/docs/react-without-es6.html) for more information. - -* * * - ### `createElement()` ```javascript @@ -248,199 +200,6 @@ Returns the `children` opaque data structure as a flat array with keys assigned * * * -### `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/docs/typechecking-with-proptypes.html). - -#### `React.PropTypes.array` - -```javascript -React.PropTypes.array -``` - -Validates that a prop is a JavaScript array primitive. - -#### `React.PropTypes.bool` - -```javascript -React.PropTypes.bool -``` - -Validates that a prop is a JavaScript bool primitive. - -#### `React.PropTypes.func` - -```javascript -React.PropTypes.func -``` - -Validates that a prop is a JavaScript function. - -#### `React.PropTypes.number` - -```javascript -React.PropTypes.number -``` - -Validates that a prop is a JavaScript number primitive. - -#### `React.PropTypes.object` - -```javascript -React.PropTypes.object -``` - -Validates that a prop is a JavaScript object. - -#### `React.PropTypes.string` - -```javascript -React.PropTypes.string -``` - -Validates that a prop is a JavaScript string primitive. - -#### `React.PropTypes.symbol` - -```javascript -React.PropTypes.symbol -``` - -Validates that a prop is a JavaScript symbol. - -#### `React.PropTypes.node` - -```javascript -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` - -```javascript -React.PropTypes.element -``` - -Validates that a prop is a React element. - -#### `React.PropTypes.instanceOf()` - -```javascript -React.PropTypes.instanceOf(class) -``` - -Validates that a prop is an instance of a class. This uses JavaScript's `instanceof` operator. - -#### `React.PropTypes.oneOf()` - -```javascript -React.PropTypes.oneOf(arrayOfValues) -``` - -Validates that a prop is limited to specific values by treating it as an enum. - -```javascript -MyComponent.propTypes = { - optionalEnum: React.PropTypes.oneOf(['News', 'Photos']), -} -``` - -#### `React.PropTypes.oneOfType()` - -```javascript -React.PropTypes.oneOfType(arrayOfPropTypes) -``` - -Validates that a prop is an object that could be one of many types. - -```javascript -MyComponent.propTypes = { - optionalUnion: React.PropTypes.oneOfType([ - React.PropTypes.string, - React.PropTypes.number, - React.PropTypes.instanceOf(Message) - ]), -} -``` - -#### `React.PropTypes.arrayOf()` - -```javascript -React.PropTypes.arrayOf(propType) -``` - -Validates that a prop is an array of a certain type. - -```javascript -MyComponent.propTypes = { - optionalArrayOf: React.PropTypes.arrayOf(React.PropTypes.number), -} -``` - -#### `React.PropTypes.objectOf()` - -```javascript -React.PropTypes.objectOf(propType) -``` - -Validates that a prop is an object with property values of a certain type. - -```javascript -MyComponent.propTypes = { - optionalObjectOf: React.PropTypes.objectOf(React.PropTypes.number), -} -``` - -#### `React.PropTypes.shape()` - -```javascript -React.PropTypes.shape(object) -``` - -Validates that a prop is an object taking on a particular shape. - -```javascript -MyComponent.propTypes = { - optionalObjectWithShape: React.PropTypes.shape({ - color: React.PropTypes.string, - fontSize: React.PropTypes.number - }), -} -``` - -#### `React.PropTypes.any` - -```javascript -React.PropTypes.any -``` - -Validates that a prop has a value of any data type. Usually followed by `isRequired`. - -```javascript -MyComponent.propTypes = { - requiredAny: React.PropTypes.any.isRequired, -} -``` - -### `isRequired` - -```javascript -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. - -```javascript -MyComponent.propTypes = { - requiredFunc: React.PropTypes.func.isRequired, -} -``` - -* * * - ### `React.addons` ```javascript diff --git a/docs/docs/typechecking-with-proptypes.md b/docs/docs/typechecking-with-proptypes.md index e3c4abd200cb1..63c3241c2e1ce 100644 --- a/docs/docs/typechecking-with-proptypes.md +++ b/docs/docs/typechecking-with-proptypes.md @@ -2,8 +2,13 @@ id: typechecking-with-proptypes title: Typechecking With PropTypes permalink: docs/typechecking-with-proptypes.html +redirect_from: + - "docs/react-api.html#typechecking-with-proptypes" --- +> Note: +> `React.PropTypes` is deprecated as of React v15.5. Please use [the `prop-types` library instead](https://github.com/aackerman/PropTypes). + As your app grows, you can catch a lot of bugs with typechecking. For some applications, you can use JavaScript extensions like [Flow](https://flowtype.org/) or [TypeScript](https://www.typescriptlang.org/) to typecheck your whole application. But even if you don't use those, React has some built-in typechecking abilities. To run typechecking on the props for a component, you can assign the special `propTypes` property: ```javascript diff --git a/docs/warnings/dont-call-proptypes.md b/docs/warnings/dont-call-proptypes.md index cb5181c931d26..bc468689af3ba 100644 --- a/docs/warnings/dont-call-proptypes.md +++ b/docs/warnings/dont-call-proptypes.md @@ -4,6 +4,9 @@ layout: single permalink: warnings/dont-call-proptypes.html --- +> Note: +> `React.PropTypes` is deprecated as of React v15.5. Please use [the `prop-types` library instead](https://github.com/aackerman/PropTypes). + In a future major release of React, the code that implements PropType validation functions will be stripped in production. Once this happens, any code that calls these functions manually (that isn't stripped in production) will throw an error. ### Declaring PropTypes is still fine