diff --git a/docs/css-prop.mdx b/docs/css-prop.mdx index d3abce3ed..98f394bde 100644 --- a/docs/css-prop.mdx +++ b/docs/css-prop.mdx @@ -13,7 +13,7 @@ There are 2 ways to get started with the `css` prop. Both methods result in the same compiled code. After adding the preset or setting the pragma as a comment, compiled jsx code will use emotion's `jsx` function instead of `React.createElement`. - + | | Input | Output | | ------ | -------------------------- | --------------------------------------------------- | | Before | `` | `React.createElement('img', { src: 'avatar.png' })` | @@ -32,6 +32,16 @@ Use the [JSX Pragma](#jsx-pragma) method instead. } ``` +If you are using the compatible React version (`>=16.14.0`) and a compatible version of `@emotion/core` (`>=10.1.0`) then you can opt into using [the new JSX runtimes](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) by using such configuration: + +**.babelrc** + +```json +{ + "presets": [["@emotion/babel-preset-css-prop", { "runtime": "automatic" }]] +} +``` + > [Full `@emotion/babel-preset-css-prop` documentation](https://emotion.sh/docs/@emotion/babel-preset-css-prop) #### JSX Pragma @@ -45,6 +55,8 @@ This option works best for testing out the `css` prop feature or in projects whe Similar to a comment containing linter configuration, this configures the [jsx babel plugin](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx) to use the `jsx` function instead of `React.createElement`. +If you are using a zero-config tool with automatic detection of which runtime (classic vs. automatic) should be used and you are already using a React version that has [the new JSX runtimes](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) (hence `runtime: 'automatic'` being configured automatically for you) such as Create React App 4 then `/** @jsx jsx */` pragma might not work and you should use `/** @jsxImportSource @emotion/core */` instead. Keep in mind that this also requires a compatible version of `@emotion/core` which is `^10.1.0`. + > [JSX Pragma Babel Documentation](https://babeljs.io/docs/en/babel-plugin-transform-react-jsx#pragma) #### Import the `jsx` function from `@emotion/core` @@ -247,4 +259,4 @@ Relying on the css spec's ["Order of Appearance"](https://www.w3.org/TR/css-casc ## Gotchas -- If you include the plugin `babel-plugin-transform-react-inline-elements` in your `.babelrc` your styles will not be applied. The plugin is not compatible with the `css` prop. \ No newline at end of file +- If you include the plugin `babel-plugin-transform-react-inline-elements` in your `.babelrc` your styles will not be applied. The plugin is not compatible with the `css` prop. diff --git a/packages/babel-preset-css-prop/README.md b/packages/babel-preset-css-prop/README.md index 1d4d7a0b3..b7fe9be18 100644 --- a/packages/babel-preset-css-prop/README.md +++ b/packages/babel-preset-css-prop/README.md @@ -66,14 +66,14 @@ require('@babel/core').transform(code, { ## Features -This preset enables the `css` prop for an entire project via a single entry to the babel configuration. After adding the preset, compiled jsx code will use emotion's `jsx` function instead of `React.createElement`. +This preset enables the `css` prop for an entire project via a single entry to the babel configuration. After adding the preset, compiled JSX code will use Emotion's JSX factories instead of the ones provided by React. | | Input | Output | | ------ | -------------------------- | --------------------------------------------------- | | Before | `` | `React.createElement('img', { src: 'avatar.png' })` | | After | `` | `jsx('img', { src: 'avatar.png' })` | -`import { jsx } from '@emotion/core'` is automatically added to the top of files where required. +Import to `@emotion/core`'s appropriate JSX factory is automatically added to the top of files where required. ## Example @@ -127,7 +127,7 @@ const Link = props => ) ``` -_In addition to the custom pragma, this example includes `babel-plugin-emotion` transforms that are enabled by default._ +_In addition to the custom JSX factory, this example includes `babel-plugin-emotion` transforms that are enabled by default._ ## Options @@ -139,6 +139,8 @@ Options for both `babel-plugin-emotion` and `@babel/plugin-transform-react-jsx` > > - [`@babel/plugin-transform-react-jsx`](https://babeljs.io/docs/en/next/babel-plugin-transform-react-jsx) +You can opt into [the new JSX runtimes](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) by configuring this preset with `{ runtime: 'automatic' }`. Keep in mind that you have to use compatible React version (`>=16.14.0`) to use this option and a compatible version of `@emotion/core` (`>=10.1.0`). + ### Examples ```json