diff --git a/docs/api/wrapper/is.md b/docs/api/wrapper/is.md
index 648f852c2..9aea5978a 100644
--- a/docs/api/wrapper/is.md
+++ b/docs/api/wrapper/is.md
@@ -1,5 +1,20 @@
 ## is
 
+::: warning Deprecation warning
+Using `is` to assert that DOM node or `vm` matches selector is deprecated and will be removed.
+
+Consider a custom matcher such as those provided in [jest-dom](https://github.com/testing-library/jest-dom#custom-matchers).
+or for DOM element type assertion use native [`Element.tagName`](https://developer.mozilla.org/en-US/docs/Web/API/Element/tagName) instead.
+
+To keep these tests, a valid replacement for:
+
+- `is('DOM_SELECTOR')` is a assertion of `wrapper.element.tagName`.
+- `is('ATTR_NAME')` is a truthy assertion of `wrapper.attributes('ATTR_NAME')`.
+- `is('CLASS_NAME')` is a truthy assertion of `wrapper.classes('CLASS_NAME')`.
+
+When using with findComponent, access the DOM element with `findComponent(Comp).element`
+:::
+
 Assert `Wrapper` DOM node or `vm` matches [selector](../selectors.md).
 
 - **Arguments:**