{"record":{"id":"b92abc6e9775a9f9","repo":"heroui-inc/heroui","slug":"ref-was-not-connected-to-dom-element-returned-by-c","errorCode":null,"errorMessage":"Ref was not connected to DOM element returned by custom `render` function. Did you forget to pass through or merge the `ref`?","messagePattern":"Ref was not connected to DOM element returned by custom `render` function\\. Did you forget to pass through or merge the `ref`\\?","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/react/src/utils/dom.tsx","lineNumber":45,"sourceCode":"   * * Only a single root DOM element can be rendered (no fragments).\n   * * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.\n   */\n  render?: DOMRenderFunction<E, T>;\n}\n\n// eslint-disable-next-line react-refresh/only-export-components\nfunction DOMElement(\n  ElementType: string,\n  props: DOMRenderProps<any, any> & AllHTMLAttributes<HTMLElement> & {ref?: React.Ref<HTMLElement>},\n) {\n  const {ref: forwardedRef, render, ...otherProps} = props;\n  const elementRef = useRef<HTMLElement | null>(null);\n  const ref = useMemo(() => mergeRefs(forwardedRef, elementRef), [forwardedRef, elementRef]);\n\n  useLayoutEffect(() => {\n    if (typeof process !== \"undefined\" && process.env?.[\"NODE_ENV\"] !== \"production\" && render) {\n      if (!elementRef.current) {\n        console.warn(\n          \"Ref was not connected to DOM element returned by custom `render` function. Did you forget to pass through or merge the `ref`?\",\n        );\n      }\n    }\n  }, [ElementType, render]);\n\n  const domProps: any = {...otherProps, ref};\n\n  if (render) {\n    return render(domProps, undefined);\n  }\n\n  return <ElementType {...domProps} />;\n}\n\ntype DOMComponents = {\n  [E in keyof React.JSX.IntrinsicElements]: (\n    props: DOMRenderProps<E, any> & React.JSX.IntrinsicElements[E],","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/heroui-inc/heroui/blob/7546fff8136f538a2f56a52257c621a5cd616a1d/packages/react/src/utils/dom.tsx#L27-L63","documentation":"When a component's `render` prop replaces the default DOM element, HeroUI merges its forwarded ref into the rendered output via mergeRefs. A layout effect checks (in non-production builds) that the ref actually got attached; if the custom render result never receives the ref, the internal element reference stays null and this console warning fires, because features like focus, measurement, or positioning that rely on the ref will silently break.","triggerScenarios":"Passing render={(props) => <MyDiv />} or render={<MyDiv />} where MyDiv does not accept/forward props.ref to its DOM element; forwarding only some props (e.g. spreading {...rest} but omitting ref, or using a component that doesn't forward refs).","commonSituations":"Using a styled custom element or non-forwardRef function component as the render target; memoized wrappers that drop the ref; converting render props from spread syntax to explicit props and forgetting ref.","solutions":["Pass all props through: render={(props) => <MyDiv {...props} />} so ref and other injected props reach the DOM","If the render target is your own component, wrap it in React.forwardRef and attach the ref to its root DOM node","Ensure any intermediate wrapper forwards refs (avoid plain function components that discard ref in React 19- setups)"],"exampleFix":"// before\n<TooltipTrigger render={(props) => <StyledSpan>{props.children}</StyledSpan>} />\n\n// after\n<TooltipTrigger render={(props) => <StyledSpan {...props} />} />","handlingStrategy":"validation","validationCode":"// Always forward the full props object to the render target so ref is included:\n<Comp render={(props) => <Custom {...props} />} />;","typeGuard":"// For custom components, ensure forwardRef is used:\nconst Custom = React.forwardRef<HTMLSpanElement, React.HTMLAttributes<HTMLSpanElement>>(\n  (props, ref) => <span ref={ref} {...props} />,\n);","tryCatchPattern":null,"preventionTips":["Always spread the full render props onto the custom element","Use forwardRef (or ref-accepting components) for render targets","Test render-prop customizations in dev builds to catch the warning early"],"tags":["react","refs","render-prop","console-warning","forwardref"],"backgroundTag":"ref-not-forwarded-in-custom-render","analyzedSha":"7546fff8136f538a2f56a52257c621a5cd616a1d","analyzedAt":"2026-08-28T13:15:49.959Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}