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