{"record":{"id":"28a5561faa5f8fc3","repo":"tailwindlabs/headlessui","slug":"did-you-forget-to-passthrough-the-ref-to-the-act-28a556","errorCode":null,"errorMessage":"Did you forget to passthrough the `ref` to the actual DOM node?","messagePattern":"Did you forget to passthrough the `ref` to the actual DOM node\\?","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@headlessui-react/src/components/transition/transition.tsx","lineNumber":364,"sourceCode":"    // Make sure that we are visible\n    if (show && treeState !== TreeStates.Visible) {\n      setState(TreeStates.Visible)\n      return\n    }\n\n    return match(treeState, {\n      [TreeStates.Hidden]: () => unregister(container),\n      [TreeStates.Visible]: () => register(container),\n    })\n  }, [treeState, container, register, unregister, show, strategy])\n\n  let ready = useServerHandoffComplete()\n\n  useIsoMorphicEffect(() => {\n    if (!requiresRef) return\n\n    if (ready && treeState === TreeStates.Visible && container.current === null) {\n      throw new Error('Did you forget to passthrough the `ref` to the actual DOM node?')\n    }\n  }, [container, treeState, ready, requiresRef])\n\n  // Skipping initial transition\n  let skip = initial && !appear\n  let immediate = appear && show && initial\n\n  let isTransitioning = useRef(false)\n\n  let nesting = useNesting(() => {\n    // When all children have been unmounted we can only hide ourselves if and\n    // only if we are not transitioning ourselves. Otherwise we would unmount\n    // before the transitions are finished.\n    if (isTransitioning.current) return\n\n    setState(TreeStates.Hidden)\n    unregister(container)\n  }, parentNesting)","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/tailwindlabs/headlessui/blob/eea57cf46fd6767ed1059012f7073b88eb159fba/packages/@headlessui-react/src/components/transition/transition.tsx#L346-L382","documentation":"When a Transition.Child is visible and the server handoff is complete, Headless UI applies transitions to the DOM node referenced by container (the forwarded ref). If container.current is still null at that point, the ref was never attached to a real DOM node — usually because a custom `as` component didn't forward its ref. The throw is a debug aid pinpointing the broken ref chain.","triggerScenarios":"Passing as={MyComponent} to Transition/Transition.Child where MyComponent doesn't forward the ref (class components, or function components without React.forwardRef); wrapping the child in a custom component that accepts but ignores/spreads away the ref; libraries like styled-components/emotion versions or HOCs that swallow refs; React 19 ref-as-prop components that accidentally shadow the ref.","commonSituations":"Using a custom component or styled wrapper as the `as` prop; migrating to wrappers that forgot forwardRef; using third-party UI wrappers around Headless UI that don't forward refs.","solutions":["Wrap the custom `as` component in React.forwardRef and spread the ref onto its root DOM element","Use as={Fragment} and put className/transition classes on an inner plain element instead","Pass the transition classes manually via className on your own wrapper and skip `as`","If using a third-party wrapper, upgrade it or check that it forwards refs to Headless UI components"],"exampleFix":"// before\nfunction Panel(props) {\n  return <div {...props} /> // ref dropped\n}\n<Transition.Child as={Panel} ... />\n\n// after\nconst Panel = React.forwardRef((props, ref) => (\n  <div {...props} ref={ref} />\n))\n<Transition.Child as={Panel} ... />","handlingStrategy":"validation","validationCode":"const forwardsRef = (Component) =>\n  Component === Fragment ||\n  typeof Component === 'string' ||\n  Component?.$$typeof === Symbol.for('react.forward_ref');\n\nconst As = forwardsRef(MyComponent) ? MyComponent : 'div';\n<Transition.Child as={As} ...>","typeGuard":"const isForwardRefComponent = (c) =>\n  typeof c === 'function' && c.$$typeof === Symbol.for('react.forward_ref');","tryCatchPattern":null,"preventionTips":["Only use `as` with host tags, Fragment, or React.forwardRef components","Spread the ref in every custom `as` component","Prefer as={Fragment} and put classes on an inner div"],"tags":["headlessui","react","transition","ref","forwardref"],"backgroundTag":"ref-not-forwarded","analyzedSha":"eea57cf46fd6767ed1059012f7073b88eb159fba","analyzedAt":"2026-08-28T19:22:46.163Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}