Throw an actionable invariant for non-DOM custom component refs

Bailing silently out of renderHTML kept the frame loop alive but left
motion.create() components that don't forward a ref to an element doing
nothing at all, with no indication why.

Throw a "custom-component-ref" invariant at mount instead, pointing at
https://motion.dev/troubleshooting/custom-component-ref. This surfaces
in React with a component stack, so the offending component is named.

The renderHTML bail stays for production, where invariants are no-ops.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mattgperry

packages/framer-motion/src/motion/__tests__/custom-non-dom-ref.test.tsx

@@ -1,21 +1,29 @@
 import * as React from "react"
 import { motion } from "../.."
-import { nextFrame } from "../../gestures/__tests__/utils"
 import { render } from "../../jest.setup"
 
 /**
  * Regression test for #2777
  *
- * When `motion()` wraps a custom component whose ref does not resolve to a DOM
- * element (e.g. the inner component is a class component, so its ref is the
- * class instance rather than a styleable element), the render loop would throw
- * `Cannot convert undefined or null to object` / `Cannot set properties of
- * undefined` when trying to write styles to `instance.style`.
+ * When `motion.create()` wraps a custom component whose ref doesn't resolve to
+ * a DOM element (e.g. the inner component is a class component, so its ref is
+ * the class instance rather than a styleable element), the render loop would
+ * throw `Cannot convert undefined or null to object` from deep inside the
+ * frame loop, breaking every animation on the page.
  *
- * Motion should not crash the whole frame loop in this case.
+ * Motion should instead throw an actionable invariant at mount.
  */
-describe("motion() wrapping a custom component with a non-DOM ref", () => {
-    test("does not throw when the inner ref is not a DOM element", async () => {
+describe("motion.create() wrapping a custom component with a non-DOM ref", () => {
+    let consoleError: jest.SpyInstance
+
+    beforeEach(() => {
+        // React logs uncaught errors thrown from refs, which is noise here.
+        consoleError = jest.spyOn(console, "error").mockImplementation(() => {})
+    })
+
+    afterEach(() => consoleError.mockRestore())
+
+    test("throws an actionable invariant when the ref isn't an element", () => {
         class ClassButton extends React.Component<any> {
             render() {
                 return <button>{this.props.children}</button>
@@ -30,11 +38,22 @@ describe("motion() wrapping a custom component with a non-DOM ref", () => {
 
         const MotionButton = motion.create(AnimateButton)
 
-        expect(() => {
+        expect(() =>
             render(<MotionButton initial={{ opacity: 0 }}>BUY</MotionButton>)
-        }).not.toThrow()
+        ).toThrowError(
+            "motion.create() components must forward their ref to a HTML or SVG element. For more information and steps for solving, visit https://motion.dev/troubleshooting/custom-component-ref"
+        )
+    })
 
-        await nextFrame()
-        await nextFrame()
+    test("mounts without error when the ref resolves to an element", () => {
+        const AnimateButton = React.forwardRef<HTMLButtonElement, any>(
+            (props, ref) => <button ref={ref} {...props} />
+        )
+
+        const MotionButton = motion.create(AnimateButton)
+
+        expect(() =>
+            render(<MotionButton initial={{ opacity: 0 }}>BUY</MotionButton>)
+        ).not.toThrow()
     })
 })

packages/motion-dom/src/render/html/HTMLVisualElement.ts

@@ -1,4 +1,4 @@
-import type { Box } from "motion-utils"
+import { invariant, type Box } from "motion-utils"
 import type { AnyResolvedKeyframe } from "../../animation/types"
 import { isCSSVariableName } from "../../animation/utils/is-css-variable"
 import type { MotionNodeOptions } from "../../node/types"
@@ -28,6 +28,21 @@ export class HTMLVisualElement extends DOMVisualElement<
 > {
     type = "html"
 
+    mount(instance: HTMLElement) {
+        /**
+         * If a custom component forwards its ref to something other than a
+         * HTML/SVG element (a class instance, an imperative handle) there's
+         * nothing for Motion to style, measure or attach gestures to.
+         */
+        invariant(
+            Boolean(instance.style),
+            "motion.create() components must forward their ref to a HTML or SVG element",
+            "custom-component-ref"
+        )
+
+        super.mount(instance)
+    }
+
     readValueFromInstance(
         instance: HTMLElement,
         key: string

packages/motion-dom/src/render/html/utils/__tests__/render.test.ts

@@ -0,0 +1,30 @@
+import { HTMLRenderState } from "../../types"
+import { renderHTML } from "../render"
+
+const createRenderState = (): HTMLRenderState => ({
+    transform: {},
+    transformOrigin: {},
+    style: { opacity: 0.5 },
+    vars: { "--test": "1" },
+})
+
+describe("renderHTML", () => {
+    test("renders styles and CSS variables to the element", () => {
+        const element = document.createElement("div")
+
+        renderHTML(element, createRenderState())
+
+        expect(element.style.opacity).toBe("0.5")
+        expect(element.style.getPropertyValue("--test")).toBe("1")
+    })
+
+    /**
+     * In development this is caught by the "custom-component-ref" invariant at
+     * mount. In production we must not take the whole render loop down. #2777
+     */
+    test("bails out if the instance isn't styleable", () => {
+        const instance = {} as HTMLElement
+
+        expect(() => renderHTML(instance, createRenderState())).not.toThrow()
+    })
+})

packages/motion-dom/src/render/html/utils/render.ts

@@ -9,9 +9,9 @@ export function renderHTML(
 ) {
     const elementStyle = element.style
 
-    // If the rendered instance isn't a styleable element (e.g. a custom
-    // component forwarded its ref to a non-DOM instance), there's nothing to
-    // render to. Bailing out here keeps the render loop from crashing. #2777
+    // A non-styleable instance throws a "custom-component-ref" invariant on
+    // mount in development. In production we bail rather than take the whole
+    // render loop down with it. #2777
     if (!elementStyle) return
 
     let key: string