CoreUI React 5.9.0 is not fully compatible with React 19 due to deprecatedelement.ref access in theCFocusTrap component. This causes console warnings and will break in future React versions.

Environment

• React: 19.1.1
• React DOM: 19.1.1
• CoreUI React: 5.9.0
• CoreUI Core: 5.4.3
• Node: 18+
• Browser: Chrome/Firefox (latest)

Error Message

FormModal.js:85 Accessing element.ref was removed in React 19. ref is now a regular prop. It will be removed from the JSX Element type in a future release.

Stack Trace

CFocusTrap @ CFocusTrap.js:154CModal @ CModal.js:96FormModal @ FormModal.js:85

Root Cause Analysis

After investigating the CoreUI React source code, we identified the issue in theCFocusTrap component:

Location 1:src/components/focus-trap/CFocusTrap.tsx (Line 248)

// ❌ Deprecated in React 19constchildRef=(onlyChildasReact.ReactElement&{ref?:React.Ref<HTMLElement>}).ref

Location 2:dist/cjs/components/focus-trap/CFocusTrap.js (Line 154)

// ❌ Deprecated in React 19constchildRef=onlyChild.ref;

React 19 removed directelement.ref access. Refs should now be accessed throughelement.props.ref.

Affected Components

• CFocusTrap (directly)
• CModal (uses CFocusTrap)
• COffcanvas (uses CFocusTrap)
• Any component using modals or offcanvas

Steps to Reproduce

1. Create a new React 19 app
2. Install CoreUI React 5.9.0:

   npm install @coreui/react@5.9.0

3. Create a simple modal component:

   import{CModal,CModalHeader,CModalBody,CButton}from'@coreui/react';functionApp(){const[visible,setVisible]=useState(false);return(<><CButtononClick={()=>setVisible(true)}>Open Modal</CButton><CModalvisible={visible}onClose={()=>setVisible(false)}><CModalHeader>Test Modal</CModalHeader><CModalBody>Content</CModalBody></CModal></>);}

4. Run the app and open the modal
5. Check browser console for React 19 warning

Proposed Solution

Replace deprecatedelement.ref access with React 19 compatibleelement.props.ref:

TypeScript Source (src/components/focus-trap/CFocusTrap.tsx):

  // Attach our ref to the ONLY child — no extra wrappers  const onlyChild = React.Children.only(children)- const childRef = (onlyChild as React.ReactElement & { ref?: React.Ref<HTMLElement> }).ref+ // React 19 compatibility: access ref through props instead of deprecated element.ref+ const childRef = onlyChild.props.ref  const mergedRef = mergeRefs(childRef, (node: HTMLElement | null) => {    containerRef.current = node  })

Compiled JavaScript (dist/cjs/components/focus-trap/CFocusTrap.js):

  // Attach our ref to the ONLY child — no extra wrappers  const onlyChild = React.Children.only(children);- const childRef = onlyChild.ref;+ // React 19 compatibility: access ref through props instead of deprecated element.ref+ const childRef = onlyChild.props.ref;  const mergedRef = utils.mergeRefs(childRef, (node) => {    containerRef.current = node;  });

Workaround

Until this is fixed in CoreUI, users can apply a patch usingpatch-package:

1. Install patch-package:

   npm install --save-dev patch-package postinstall-postinstall

2. Modify the files as shown above

3. Create the patch:

   npx patch-package @coreui/react

4. Add topackage.json:

   {"scripts": {"postinstall":"patch-package"  }}

The patch will automatically apply onnpm install.

Testing

We have tested this fix in production and confirmed:

• ✅ React 19 warnings eliminated
• ✅ Modal functionality fully preserved
• ✅ Focus management working correctly
• ✅ Keyboard navigation (Tab, Escape) working
• ✅ All existing features functional
• ✅ No performance impact

Additional Context

This is a breaking change in React 19 as documented in theReact 19 Upgrade Guide:

In React 19,ref is treated as a regular prop, and accessingelement.ref is deprecated. Useelement.props.ref instead.

References

• React 19 Upgrade Guide:https://19.react.dev/blog/2024/04/25/react-19-upgrade-guide
• React 19 Release Notes:https://react.dev/blog/2024/12/05/react-19
• Our detailed investigation: [Link to your repo documentation if public]

Would You Like Help?

We have a working patch and would be happy to submit a PR if that would be helpful. We've tested this fix thoroughly in our production application.

Note: This issue affects all users upgrading to React 19. An official fix would greatly benefit the CoreUI community.