diff --git a/CHANGELOG.md b/CHANGELOG.md
index 72e96eeabb..bae48b418d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
* [`no-unknown-property`]: add onMouseMoveCapture as valid react-specific attribute ([#3390][] @sjarva)
* [`no-unknown-property`]: make onLoad and onError be accepted on more elements ([#3390][] @sjarva)
+### Changed
+
+* [Docs] [`no-unknown-property`]: add a mention about using ignores properties with libraries that add props ([#3390][] @sjarva)
+
[#3390]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3390
[#3388]: https://github.com/jsx-eslint/eslint-plugin-react/issues/3388
diff --git a/docs/rules/no-unknown-property.md b/docs/rules/no-unknown-property.md
index 108fa42a44..d142def850 100644
--- a/docs/rules/no-unknown-property.md
+++ b/docs/rules/no-unknown-property.md
@@ -43,7 +43,6 @@ var AnotherComponent = ;
// Custom web components are ignored
var MyElem =
;
var AtomPanel = ;
-
```
## Rule Options
@@ -57,6 +56,23 @@ var AtomPanel = ;
- `enabled`: for enabling the rule. 0=off, 1=warn, 2=error. Defaults to 0.
- `ignore`: optional array of property and attribute names to ignore during validation.
+If you are using a library that passes something as a prop to JSX elements, it is recommended to add those props to the ignored properties.
+
+For example, if you use [emotion](https://emotion.sh/docs/introduction) and its [`css` prop](https://emotion.sh/docs/css-prop)),
+add the following to your `.eslintrc` config file:
+
+```js
+...
+"react/no-unknown-property": ['error', { ignore: ['css'] }]
+...
+```
+
+Now, the following code passes:
+
+```jsx
+var StyledDiv = ;
+```
+
## When Not To Use It
If you are not using JSX you can disable this rule.
diff --git a/tests/lib/rules/no-unknown-property.js b/tests/lib/rules/no-unknown-property.js
index 411d316d25..5312003511 100644
--- a/tests/lib/rules/no-unknown-property.js
+++ b/tests/lib/rules/no-unknown-property.js
@@ -94,6 +94,10 @@ ruleTester.run('no-unknown-property', rule, {
code: ';',
options: [{ ignore: ['someProp'] }],
},
+ {
+ code: ';',
+ options: [{ ignore: ['css'] }],
+ },
// aria-* attributes should work
{ code: ';' },