From 566406e717a5cae4151a195168d3b62df352ac1f Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Tue, 6 Mar 2018 00:16:32 -0800 Subject: [PATCH 01/10] Add docs for new Context API (R16.3) --- content/docs/context.md | 90 ++++++++++++++----- examples/context/theme-detailed-app.js | 37 ++++++++ .../context/theme-detailed-theme-context.js | 5 ++ .../context/theme-detailed-themed-button.js | 18 ++++ examples/context/theme-example.js | 42 +++++++++ 5 files changed, 172 insertions(+), 20 deletions(-) create mode 100644 examples/context/theme-detailed-app.js create mode 100644 examples/context/theme-detailed-theme-context.js create mode 100644 examples/context/theme-detailed-themed-button.js create mode 100644 examples/context/theme-example.js diff --git a/content/docs/context.md b/content/docs/context.md index 1a648042..05af3314 100644 --- a/content/docs/context.md +++ b/content/docs/context.md @@ -4,35 +4,71 @@ title: Context permalink: docs/context.html --- -> Note: -> -> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`. -> ->We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion. +Context provides a way to pass data through the component tree without having to pass props down manually at every level. + +## Using Context + +Here is an example illustrating how you might inject a "theme" using context: + +`embed:context/theme-example.js` + +### API + +#### `React.createContext` + +```js +const {Provider, Consumer} = React.createContext([default]); +``` + +Creates a `{ Provider, Consumer }` pair. + +Takes one argument, the default context that Consumers will receive when they don't have a matching Provider. + + +#### `Provider` + +```js + +``` -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. +A React component that allows Consumers to subscribe to context changes. -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. +Takes one prop, `value`, which will be passed to the [render prop](/docs/render-props.html) of child Consumers for the matching context anywhere in the component tree. One Provider can be connected to many Consumers. + +#### `Consumer` + +```js + + { value => { /* render something based on the context value */ } } + +``` + +A React component that subscribes to context changes. + +Takes a function as the `children` prop that receives the `value` prop of the matching Provider. This function will be called whenever the Provider's value is updated. > Note: > -> A [new, safe version of context](https://github.com/reactjs/rfcs/blob/master/text/0002-new-version-of-context.md) is under development for the upcoming 16.3 release. +> For more information about this pattern, see [render props](/docs/render-props.html). + +### Typical Usage +`embed:context/theme-detailed-theme-context.js` -## Why Not To Use Context +`embed:context/theme-detailed-themed-button.js` -The vast majority of applications do not need to use context. +`embed:context/theme-detailed-app.js` -If you want your application to be stable, don't use context. It is an experimental API and it is likely to break in future releases of React. -If you aren't familiar with state management libraries like [Redux](https://github.com/reactjs/redux) or [MobX](https://github.com/mobxjs/mobx), don't use context. For many practical applications, these libraries and their React bindings are a good choice for managing state that is relevant to many components. It is far more likely that Redux is the right solution to your problem than that context is the right solution. +## Experimental API (Deprecated in React 16.3) -If you're still learning React, don't use context. There is usually a better way to implement functionality just using props and state. +> The old experimental API is deprecated as of React 16.3. The API will be supported in all 16.x releases, but applications using it should migrate to the new API. -If you insist on using context despite these warnings, try to isolate your use of context to a small area and avoid using the context API directly when possible so that it's easier to upgrade when the API changes. +The experimental API lacked a safe mechanism to update context. Version 16.3 introduced a new context API that is more efficient and supports both static type checking and deep updates. -## How To Use Context +### How To Use Context + +> This section documents a deprecated API Suppose you have a structure like: @@ -119,7 +155,15 @@ By adding `childContextTypes` and `getChildContext` to `MessageList` (the contex If `contextTypes` is not defined, then `context` will be an empty object. -## Parent-Child Coupling +> Note: +> +> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`. +> +> We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion. + +### Parent-Child Coupling + +> This section documents a deprecated API Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router): @@ -149,7 +193,9 @@ By passing down some information from the `Router` component, each `Link` and `R Before you build components with an API similar to this, consider if there are cleaner alternatives. For example, you can pass entire React components as props if you'd like to. -## Referencing Context in Lifecycle Methods +### Referencing Context in Lifecycle Methods + +> This section documents a deprecated API If `contextTypes` is defined within a component, the following [lifecycle methods](/docs/react-component.html#the-component-lifecycle) will receive an additional parameter, the `context` object: @@ -162,7 +208,9 @@ If `contextTypes` is defined within a component, the following [lifecycle method > > As of React 16, `componentDidUpdate` no longer receives `prevContext`. -## Referencing Context in Stateless Functional Components +### Referencing Context in Stateless Functional Components + +> This section documents a deprecated API 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. @@ -177,7 +225,9 @@ const Button = ({children}, context) => Button.contextTypes = {color: PropTypes.string}; ``` -## Updating Context +### Updating Context + +> This section documents a deprecated API Don't do it. diff --git a/examples/context/theme-detailed-app.js b/examples/context/theme-detailed-app.js new file mode 100644 index 00000000..4cbd4669 --- /dev/null +++ b/examples/context/theme-detailed-app.js @@ -0,0 +1,37 @@ +import ThemeContext from './theme-context'; +import ThemedButton from './button'; + +class App extends React.Component { + state = { + theme: { + highlight: 'blue', + accent: 'purple', + }, + }; + + changeHighlightColor = () => { + const colors = ['red', 'blue', 'green']; + const randomColor = + colors[Math.floor(Math.random() * 3)]; + this.setState({ + theme: { + ...this.state.theme, + highlight: randomColor, + }, + }); + }; + + render() { + return ( + +
+ + Change Theme + +
+ + ); + } +} + +ReactDOM.render(, document.root); diff --git a/examples/context/theme-detailed-theme-context.js b/examples/context/theme-detailed-theme-context.js new file mode 100644 index 00000000..75af25f8 --- /dev/null +++ b/examples/context/theme-detailed-theme-context.js @@ -0,0 +1,5 @@ +const defaultTheme = {highlight: 'blue', accent: 'purple'}; + +const ThemeContext = React.createContext(defaultTheme); + +export default ThemeContext; diff --git a/examples/context/theme-detailed-themed-button.js b/examples/context/theme-detailed-themed-button.js new file mode 100644 index 00000000..6ec33b5b --- /dev/null +++ b/examples/context/theme-detailed-themed-button.js @@ -0,0 +1,18 @@ +import ThemeContext from './theme-context'; + +class ThemedButton extends React.Component { + render() { + return ( + + {theme => ( + ); @@ -104,170 +107,8 @@ 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{6,13-15,21,28-30,40-42} -import PropTypes from 'prop-types'; - -class Button extends React.Component { - render() { - return ( - - ); - } -} - -Button.contextTypes = { - color: PropTypes.string -}; - -class Message extends React.Component { - render() { - return ( -
- {this.props.text} -
- ); - } -} - -class MessageList extends React.Component { - getChildContext() { - return {color: "purple"}; - } - - render() { - const children = this.props.messages.map((message) => - - ); - return
{children}
; - } -} - -MessageList.childContextTypes = { - color: PropTypes.string -}; -``` - -By adding `childContextTypes` and `getChildContext` to `MessageList` (the context provider), React passes the information down automatically and any component in the subtree (in this case, `Button`) can access it by defining `contextTypes`. - -If `contextTypes` is not defined, then `context` will be an empty object. - -> Note: -> -> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`. -> -> We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion. - -### Parent-Child Coupling - -> This section documents a deprecated API - -Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router): - -```javascript -import { BrowserRouter as Router, Route, Link } from 'react-router-dom'; - -const BasicExample = () => ( - -
-
    -
  • Home
    • -
  • About
    • -
  • Topics
    • -
- -
- - - - -
- -); -``` - -By passing down some information from the `Router` component, each `Link` and `Route` can communicate back to the containing `Router`. - -Before you build components with an API similar to this, consider if there are cleaner alternatives. For example, you can pass entire React components as props if you'd like to. - -### Referencing Context in Lifecycle Methods - -> This section documents a deprecated API - -If `contextTypes` is defined within a component, the following [lifecycle methods](/docs/react-component.html#the-component-lifecycle) will receive an additional parameter, the `context` object: - -- [`constructor(props, context)`](/docs/react-component.html#constructor) -- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops) -- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate) -- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate) - -> Note: -> -> As of React 16, `componentDidUpdate` no longer receives `prevContext`. - -### Referencing Context in Stateless Functional Components - -> This section documents a deprecated API - -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 -import PropTypes from 'prop-types'; - -const Button = ({children}, context) => - ; - -Button.contextTypes = {color: PropTypes.string}; -``` - -### Updating Context - -> This section documents a deprecated API - -Don't do it. - -React has an API to update context, but it is fundamentally broken and you should not use it. - -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 -import PropTypes from 'prop-types'; - -class MediaQuery extends React.Component { - constructor(props) { - super(props); - this.state = {type:'desktop'}; - } - - getChildContext() { - return {type: this.state.type}; - } - - componentDidMount() { - const checkMediaQuery = () => { - const type = window.matchMedia("(min-width: 1025px)").matches ? 'desktop' : 'mobile'; - if (type !== this.state.type) { - this.setState({type}); - } - }; - - window.addEventListener('resize', checkMediaQuery); - checkMediaQuery(); - } - - render() { - return this.props.children; - } -} - -MediaQuery.childContextTypes = { - type: PropTypes.string -}; -``` +## Legacy API -The problem is, if a context value provided by component changes, descendants that use that value won't update if an intermediate parent returns `false` from `shouldComponentUpdate`. This is totally out of control of the components using context, so there's basically no way to reliably update the context. [This blog post](https://medium.com/@mweststrate/how-to-safely-use-react-context-b7e343eff076) has a good explanation of why this is a problem and how you might get around it. +> The legacy context API was deprecated in React 16.3 +> +> React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. Read the [legacy context docs here](/docs/legacy-context.html). diff --git a/content/docs/legacy-context.md b/content/docs/legacy-context.md new file mode 100644 index 00000000..d9e899f0 --- /dev/null +++ b/content/docs/legacy-context.md @@ -0,0 +1,215 @@ +--- +id: legacy-context +title: Legacy Context +permalink: docs/legacy-context.html +--- + +> This API is deprecated as of React 16.3. +> +> The API will be supported in all 16.x releases, but applications using it should migrate to the [new API](/docs/context.html). The experimental API lacked a safe mechanism to update context. Version 16.3 introduced a new context API that is more efficient and supports both static type checking and deep updates. + +## How To Use Context + +> This section documents a deprecated API. See the [new API](/docs/context.html). + +Suppose you have a structure like: + +```javascript +class Button extends React.Component { + render() { + return ( + + ); + } +} + +class Message extends React.Component { + render() { + return ( +
+ {this.props.text} +
+ ); + } +} + +class MessageList extends React.Component { + render() { + const color = "purple"; + const children = this.props.messages.map((message) => + + ); + return
{children}
; + } +} +``` + +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{6,13-15,21,28-30,40-42} +import PropTypes from 'prop-types'; + +class Button extends React.Component { + render() { + return ( + + ); + } +} + +Button.contextTypes = { + color: PropTypes.string +}; + +class Message extends React.Component { + render() { + return ( +
+ {this.props.text} +
+ ); + } +} + +class MessageList extends React.Component { + getChildContext() { + return {color: "purple"}; + } + + render() { + const children = this.props.messages.map((message) => + + ); + return
{children}
; + } +} + +MessageList.childContextTypes = { + color: PropTypes.string +}; +``` + +By adding `childContextTypes` and `getChildContext` to `MessageList` (the context provider), React passes the information down automatically and any component in the subtree (in this case, `Button`) can access it by defining `contextTypes`. + +If `contextTypes` is not defined, then `context` will be an empty object. + +> Note: +> +> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`. +> +> We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion. + +### Parent-Child Coupling + +> This section documents a deprecated API. See the [new API](/docs/context.html). + +Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router): + +```javascript +import { BrowserRouter as Router, Route, Link } from 'react-router-dom'; + +const BasicExample = () => ( + +
+
    +
  • Home
    • +
  • About
    • +
  • Topics
    • +
+ +
+ + + + +
+ +); +``` + +By passing down some information from the `Router` component, each `Link` and `Route` can communicate back to the containing `Router`. + +Before you build components with an API similar to this, consider if there are cleaner alternatives. For example, you can pass entire React components as props if you'd like to. + +### Referencing Context in Lifecycle Methods + +> This section documents a deprecated API. See the [new API](/docs/context.html). + +If `contextTypes` is defined within a component, the following [lifecycle methods](/docs/react-component.html#the-component-lifecycle) will receive an additional parameter, the `context` object: + +- [`constructor(props, context)`](/docs/react-component.html#constructor) +- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops) +- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate) +- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate) + +> Note: +> +> As of React 16, `componentDidUpdate` no longer receives `prevContext`. + +### Referencing Context in Stateless Functional Components + +> This section documents a deprecated API. See the [new API](/docs/context.html). + +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 +import PropTypes from 'prop-types'; + +const Button = ({children}, context) => + ; + +Button.contextTypes = {color: PropTypes.string}; +``` + +### Updating Context + +> This section documents a deprecated API. See the [new API](/docs/context.html). + +Don't do it. + +React has an API to update context, but it is fundamentally broken and you should not use it. + +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 +import PropTypes from 'prop-types'; + +class MediaQuery extends React.Component { + constructor(props) { + super(props); + this.state = {type:'desktop'}; + } + + getChildContext() { + return {type: this.state.type}; + } + + componentDidMount() { + const checkMediaQuery = () => { + const type = window.matchMedia("(min-width: 1025px)").matches ? 'desktop' : 'mobile'; + if (type !== this.state.type) { + this.setState({type}); + } + }; + + window.addEventListener('resize', checkMediaQuery); + checkMediaQuery(); + } + + render() { + return this.props.children; + } +} + +MediaQuery.childContextTypes = { + type: PropTypes.string +}; +``` + +The problem is, if a context value provided by component changes, descendants that use that value won't update if an intermediate parent returns `false` from `shouldComponentUpdate`. This is totally out of control of the components using context, so there's basically no way to reliably update the context. [This blog post](https://medium.com/@mweststrate/how-to-safely-use-react-context-b7e343eff076) has a good explanation of why this is a problem and how you might get around it. \ No newline at end of file From a5022da882fda49e29603a7ad2046b26e88c7a5c Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Tue, 20 Mar 2018 18:15:23 -0700 Subject: [PATCH 03/10] Add in-page TOC Also reduce spacing between ul/li tags --- content/docs/context.md | 10 ++++++++++ src/theme.js | 3 ++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/content/docs/context.md b/content/docs/context.md index 47c0f19a..8fcb2256 100644 --- a/content/docs/context.md +++ b/content/docs/context.md @@ -6,6 +6,16 @@ permalink: docs/context.html Context provides a way to pass data through the component tree without having to pass props down manually at every level. +- [API](#api) + - [React.createContext](#reactcreatecontext) + - [Provider](#provider) + - [Consumer](#consumer) +- [Examples](#examples) + - [Static Context](#static-context) + - [Dynamic Context](#dynamic-context) +- [Motivation](#motivation) +- [Legacy API](#legacy-api) + ## API ### `React.createContext` diff --git a/src/theme.js b/src/theme.js index 9da7e3e4..5fba925d 100644 --- a/src/theme.js +++ b/src/theme.js @@ -336,7 +336,7 @@ const sharedStyles = { }, '& li': { - marginTop: 20, + marginTop: 10, }, '& li.button-newapp': { @@ -345,6 +345,7 @@ const sharedStyles = { '& ol, & ul': { marginLeft: 20, + marginTop: 10, }, }, From fe3d0a449d3f6ae31cdf938086f7f42de871f783 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Tue, 20 Mar 2018 18:29:38 -0700 Subject: [PATCH 04/10] Typo --- content/docs/context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/context.md b/content/docs/context.md index 8fcb2256..706a6370 100644 --- a/content/docs/context.md +++ b/content/docs/context.md @@ -67,7 +67,7 @@ Here is an example illustrating how you might inject a "theme" using context: A more complex example with dynamic values for the theme: -**theme-contex.js** +**theme-context.js** `embed:context/theme-detailed-theme-context.js` **themed-button.js** From 808e5bddaff2685186aec1389130d00408743dfb Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Wed, 21 Mar 2018 01:28:01 -0700 Subject: [PATCH 05/10] Rephrase and reorganize - Move Motivation to top @bvaughn - Copy in some Motivation text from the RFC for the intro para - Update examples - Remove state from simple example - Remove "random color" example; just toggle a theme variable instead - Update highlights --- content/docs/context.md | 67 +++++-------------- content/docs/legacy-context.md | 8 ++- examples/context/motivation.js | 33 +++++++++ examples/context/theme-detailed-app.js | 33 ++++----- .../context/theme-detailed-theme-context.js | 14 +++- .../context/theme-detailed-themed-button.js | 3 +- examples/context/theme-example.js | 37 ++++++---- 7 files changed, 107 insertions(+), 88 deletions(-) create mode 100644 examples/context/motivation.js diff --git a/content/docs/context.md b/content/docs/context.md index 706a6370..fd3e814b 100644 --- a/content/docs/context.md +++ b/content/docs/context.md @@ -6,6 +6,9 @@ permalink: docs/context.html Context provides a way to pass data through the component tree without having to pass props down manually at every level. +Typically, data in a React application is passed top-down (parent to child) via props. But sometimes it's useful to pass values through multiple levels without adding props to every intermediate component. Examples include a language preference, or a UI theme. Many components may rely on those but you don't want to have to pass a locale prop and a theme prop through every level of the tree. + +- [Motivation](#motivation) - [API](#api) - [React.createContext](#reactcreatecontext) - [Provider](#provider) @@ -13,21 +16,26 @@ Context provides a way to pass data through the component tree without having to - [Examples](#examples) - [Static Context](#static-context) - [Dynamic Context](#dynamic-context) -- [Motivation](#motivation) - [Legacy API](#legacy-api) + +## Motivation + +Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components. Using context, we can avoid passing props through intermediate elements. + +`embed:context/motivation.js` + ## API ### `React.createContext` ```js -const {Provider, Consumer} = React.createContext([default]); +const {Provider, Consumer} = React.createContext(defaultValue); ``` Creates a `{ Provider, Consumer }` pair. -Takes one argument, the default context that Consumers will receive when they don't have a matching Provider. - +Optionally accepts a default value to be passed to Consumers without a Provider ancestor. ### `Provider` @@ -37,7 +45,7 @@ Takes one argument, the default context that Consumers will receive when they do A React component that allows Consumers to subscribe to context changes. -Takes one prop, `value`, which will be passed to the [render prop](/docs/render-props.html) of child Consumers for the matching context anywhere in the component tree. One Provider can be connected to many Consumers. +Accepts a `value` prop to be passed to Consumers that are descendants of this Provider. One Provider can be connected to many Consumers. Providers can be nested to override values deeper within the tree. ### `Consumer` @@ -47,12 +55,12 @@ Takes one prop, `value`, which will be passed to the [render prop](/docs/render- ``` -A React component that subscribes to context changes. +A React component that subscribes to context changes. -Takes a function as the `children` prop that receives the `value` prop of the matching Provider. This function will be called whenever the Provider's value is updated. +Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). This function receives the current context value and returns a React node, and will be called whenever the Provider's value is updated. > Note: -> +> > For more information about this pattern, see [render props](/docs/render-props.html). ## Examples @@ -76,49 +84,8 @@ A more complex example with dynamic values for the theme: **app.js** `embed:context/theme-detailed-app.js` -## Motivation - -Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components. Using context, we can avoid passing props through intermediate elements. - -```js -class Button extends React.Component { - render() { - return ( - - ); - } -} - -class Message extends React.Component { - render() { - return ( -
- {/* - The Message component must take `color` as as prop to pass it to the - Button. Using context, the Button could connect to the color context - on its own. - */} - {this.props.text} -
- ); - } -} - -class MessageList extends React.Component { - render() { - const color = "purple"; - const children = this.props.messages.map((message) => - - ); - return
{children}
; - } -} -``` - ## Legacy API -> The legacy context API was deprecated in React 16.3 +> The legacy context API was deprecated in React 16.3 and will be removed in version 17. > > React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. Read the [legacy context docs here](/docs/legacy-context.html). diff --git a/content/docs/legacy-context.md b/content/docs/legacy-context.md index d9e899f0..8da900b6 100644 --- a/content/docs/legacy-context.md +++ b/content/docs/legacy-context.md @@ -4,9 +4,11 @@ title: Legacy Context permalink: docs/legacy-context.html --- -> This API is deprecated as of React 16.3. -> -> The API will be supported in all 16.x releases, but applications using it should migrate to the [new API](/docs/context.html). The experimental API lacked a safe mechanism to update context. Version 16.3 introduced a new context API that is more efficient and supports both static type checking and deep updates. +> Deprecation Warning +> +> The legacy API has been deprecated and will be removed in version 17. +> Use the [new context API](/docs/context.html) introduced with version 16.3. +> The legacy API will continue working for all 16.x releases. ## How To Use Context diff --git a/examples/context/motivation.js b/examples/context/motivation.js new file mode 100644 index 00000000..1e6ed885 --- /dev/null +++ b/examples/context/motivation.js @@ -0,0 +1,33 @@ +class Button extends React.Component { + render() { + return ( + + ); + } +} + +class Message extends React.Component { + render() { + // highlight-range{1-3} + // The Message component must take `color` as as prop to pass it + // to the Button. Using context, the Button could connect to the + // color context on its own. + return ( +
+ {this.props.text} +
+ ); + } +} + +class MessageList extends React.Component { + render() { + const color = "purple"; + const children = this.props.messages.map((message) => + + ); + return
{children}
; + } +} diff --git a/examples/context/theme-detailed-app.js b/examples/context/theme-detailed-app.js index 4cbd4669..e1ca8345 100644 --- a/examples/context/theme-detailed-app.js +++ b/examples/context/theme-detailed-app.js @@ -1,34 +1,27 @@ -import ThemeContext from './theme-context'; +import ThemeContext, {themes} from './theme-context'; import ThemedButton from './button'; class App extends React.Component { state = { - theme: { - highlight: 'blue', - accent: 'purple', - }, + theme: themes.light, }; - changeHighlightColor = () => { - const colors = ['red', 'blue', 'green']; - const randomColor = - colors[Math.floor(Math.random() * 3)]; - this.setState({ - theme: { - ...this.state.theme, - highlight: randomColor, - }, - }); + toggleTheme = () => { + this.setState(state => ({ + theme: + state.theme === themes.dark + ? themes.light + : themes.dark, + })); }; render() { + //highlight-range{2,6} return ( -
- - Change Theme - -
+ + Change Theme + ); } diff --git a/examples/context/theme-detailed-theme-context.js b/examples/context/theme-detailed-theme-context.js index 75af25f8..d8051fab 100644 --- a/examples/context/theme-detailed-theme-context.js +++ b/examples/context/theme-detailed-theme-context.js @@ -1,5 +1,15 @@ -const defaultTheme = {highlight: 'blue', accent: 'purple'}; +export const themes = { + light: { + foreground: '#ffffff', + background: '#222222', + }, + dark: { + foreground: '#000000', + background: '#eeeeee', + }, +}; -const ThemeContext = React.createContext(defaultTheme); +// highlight-next-line +const ThemeContext = React.createContext(themes.dark); export default ThemeContext; diff --git a/examples/context/theme-detailed-themed-button.js b/examples/context/theme-detailed-themed-button.js index 6ec33b5b..10c1d922 100644 --- a/examples/context/theme-detailed-themed-button.js +++ b/examples/context/theme-detailed-themed-button.js @@ -1,13 +1,14 @@ import ThemeContext from './theme-context'; class ThemedButton extends React.Component { + // highlight-range{3-10} render() { return ( {theme => ( +

{this.props.text}

+ ); } @@ -24,10 +25,10 @@ class Message extends React.Component { class MessageList extends React.Component { render() { - const color = "purple"; - const children = this.props.messages.map((message) => + const color = 'purple'; + const children = this.props.messages.map(message => ( - ); + )); return
{children}
; } } diff --git a/examples/context/theme-detailed-app.js b/examples/context/theme-detailed-app.js index e1ca8345..1b57e15d 100644 --- a/examples/context/theme-detailed-app.js +++ b/examples/context/theme-detailed-app.js @@ -1,4 +1,4 @@ -import ThemeContext, {themes} from './theme-context'; +import {ThemeContext, themes} from './theme-context'; import ThemedButton from './button'; class App extends React.Component { diff --git a/examples/context/theme-detailed-theme-context.js b/examples/context/theme-detailed-theme-context.js index d8051fab..c0f30d95 100644 --- a/examples/context/theme-detailed-theme-context.js +++ b/examples/context/theme-detailed-theme-context.js @@ -10,6 +10,6 @@ export const themes = { }; // highlight-next-line -const ThemeContext = React.createContext(themes.dark); - -export default ThemeContext; +export const ThemeContext = React.createContext( + themes.dark +); diff --git a/examples/context/theme-detailed-themed-button.js b/examples/context/theme-detailed-themed-button.js index 10c1d922..aa36ee77 100644 --- a/examples/context/theme-detailed-themed-button.js +++ b/examples/context/theme-detailed-themed-button.js @@ -1,4 +1,4 @@ -import ThemeContext from './theme-context'; +import {ThemeContext} from './theme-context'; class ThemedButton extends React.Component { // highlight-range{3-10} From 291b2fdeb8bd707d7f28231300fdf2903b45acd9 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Wed, 21 Mar 2018 10:03:08 -0700 Subject: [PATCH 07/10] Wording tweaks --- content/docs/context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/context.md b/content/docs/context.md index fd3e814b..1463720e 100644 --- a/content/docs/context.md +++ b/content/docs/context.md @@ -6,7 +6,7 @@ permalink: docs/context.html Context provides a way to pass data through the component tree without having to pass props down manually at every level. -Typically, data in a React application is passed top-down (parent to child) via props. But sometimes it's useful to pass values through multiple levels without adding props to every intermediate component. Examples include a language preference, or a UI theme. Many components may rely on those but you don't want to have to pass a locale prop and a theme prop through every level of the tree. +In a typical React application, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like this between components without having to explicitly pass a prop through every level of the tree. - [Motivation](#motivation) - [API](#api) @@ -57,7 +57,7 @@ Accepts a `value` prop to be passed to Consumers that are descendants of this Pr A React component that subscribes to context changes. -Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). This function receives the current context value and returns a React node, and will be called whenever the Provider's value is updated. +Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). This function receives the current context value and returns a React node. It will be called whenever the Provider's value is updated. > Note: > From 6aa199516d515e95ad8191902e9b95f19cd7f28b Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Wed, 21 Mar 2018 10:04:11 -0700 Subject: [PATCH 08/10] Add solution to motivation problem --- content/docs/context.md | 8 +++- .../{motivation.js => motivation-problem.js} | 0 examples/context/motivation-solution.js | 42 +++++++++++++++++++ 3 files changed, 48 insertions(+), 2 deletions(-) rename examples/context/{motivation.js => motivation-problem.js} (100%) create mode 100644 examples/context/motivation-solution.js diff --git a/content/docs/context.md b/content/docs/context.md index 1463720e..2b9ccfdd 100644 --- a/content/docs/context.md +++ b/content/docs/context.md @@ -21,9 +21,13 @@ In a typical React application, data is passed top-down (parent to child) via pr ## Motivation -Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components. Using context, we can avoid passing props through intermediate elements. +Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components: -`embed:context/motivation.js` +`embed:context/motivation-problem.js` + +Using context, we can avoid passing props through intermediate elements: + +`embed:context/motivation-solution.js` ## API diff --git a/examples/context/motivation.js b/examples/context/motivation-problem.js similarity index 100% rename from examples/context/motivation.js rename to examples/context/motivation-problem.js diff --git a/examples/context/motivation-solution.js b/examples/context/motivation-solution.js new file mode 100644 index 00000000..fbb6ac59 --- /dev/null +++ b/examples/context/motivation-solution.js @@ -0,0 +1,42 @@ +const ColorContext = React.createContext(); + +class Button extends React.Component { + render() { + // highlight-range{2-8} + return ( + + {color => ( + + )} + + ); + } +} + +class Message extends React.Component { + render() { + return ( +
+

{this.props.text}

+ +
+ ); + } +} + +class MessageList extends React.Component { + render() { + const color = 'purple'; + const children = this.props.messages.map(message => ( + + )); + // highlight-range{2-4} + return ( + + {children} + + ); + } +} From 7c6688c12cf1610ce99d61ab34f13746e3f981a5 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Wed, 21 Mar 2018 10:16:38 -0700 Subject: [PATCH 09/10] Highlight createContext() --- examples/context/motivation-solution.js | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/context/motivation-solution.js b/examples/context/motivation-solution.js index fbb6ac59..76bf72cc 100644 --- a/examples/context/motivation-solution.js +++ b/examples/context/motivation-solution.js @@ -1,3 +1,4 @@ +// highlight-range{1} const ColorContext = React.createContext(); class Button extends React.Component { From b49f99b7d1d6941e7d101eac7e93d7e4f157c939 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Wed, 21 Mar 2018 12:16:23 -0700 Subject: [PATCH 10/10] Highlight whole createContext() call --- examples/context/theme-detailed-theme-context.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/context/theme-detailed-theme-context.js b/examples/context/theme-detailed-theme-context.js index c0f30d95..80dd489a 100644 --- a/examples/context/theme-detailed-theme-context.js +++ b/examples/context/theme-detailed-theme-context.js @@ -9,7 +9,7 @@ export const themes = { }, }; -// highlight-next-line +// highlight-range{1-3} export const ThemeContext = React.createContext( themes.dark );