[New Feature] React 19 support

[kotAPI]

🚀 Feature Request

Been getting this error in the docs website after we had upgraded to React 19, we need to make sure our components are supported with React 19

Error: 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.
at createUnhandledError (webpack-internal:///(app-pages-browser)/./node_modules/.pnpm/next@15.2.8_react-

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• [New Feature] forwardRef Refactor of the entire codebase [EPIC] #1352

Related Issues

• [New Feature] Upgrade Docs nextjs version to 15.x #662
• [New Feature] Better Prop support v2 #1257
• BUG: Object literal may only specify known properties, and 'ref' does not exist in type 'Partial<unknown> & Attributes'. #622
• [New Feature] Global Jest Report Issues #1480

👤 Suggested Assignees

• kotAPI

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Summary

The component library needs to support React 19 after the docs website upgraded. The specific error "Accessing element.ref was removed in React 19" is caused by the TooltipTrigger component directly accessing the .ref property on children elements, which is no longer allowed in React 19 where refs are now regular props.

Observations

Codebase Summary

This is a React component library built with TypeScript, using Rollup for bundling and Babel for transforms. The library currently requires React ^18.2.0 and contains 196 components using forwardRef for ref handling. Most components follow standard React patterns and use useMergeRefs from @floating-ui/react for ref composition. The problematic code is isolated to TooltipTrigger.tsx which accesses (children as any).ref directly. The docs site runs separately on React 19.0.0 and imports components from the main library.

Assumptions

Assumption 1: React Version Support Strategy

Options Considered:

• Support only React 19 (breaking change, forces all users to upgrade immediately)
• Support both React 18 and React 19 (allows gradual migration for users)

Chosen Option: Support both React 18 and React 19

Rationale: This aligns with standard component library practices during major React version transitions, allowing users to migrate at their own pace while enabling new projects to use React 19. Most existing patterns are already compatible, and the fix needed is isolated to one component.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Fix React 19 Ref Access Incompatibility

This phase addresses the direct cause of the error by updating how TooltipTrigger extracts and handles refs from children elements.

Task 1: Update TooltipTrigger Ref Extraction

Remove the direct .ref property access and implement a React 19-compatible approach to extract refs from children.

• In src/components/ui/Tooltip/fragments/TooltipTrigger.tsx, replace line 26's const childrenRef = (children as any).ref; with a safer ref extraction method
• Use React.isValidElement(children) to verify children is a valid React element before attempting ref extraction
• Extract ref from children.props.ref instead of children.ref (in React 19, ref is a regular prop accessible via props)
• Handle both function refs and object refs appropriately in the extraction logic
• Keep the existing useMergeRefs call to merge the extracted ref with context.refs.setReference and the forwarded ref
• Ensure the solution works for both React 18 (where ref may exist in both locations) and React 19 (where ref is only in props)

Task 2: Review Custom Ref Composition Patterns

Verify that other custom ref handling patterns are React 19 compatible.

• Review src/components/ui/Tabs/fragments/TabTrigger.tsx and src/components/ui/TabNav/fragments/TabNavLink.tsx which use custom ref composition with useCallback and mutable ref assignments
• Verify these patterns work correctly with React 19's ref handling (they should, as they use standard mutable ref patterns)
• Consider refactoring to use useMergeRefs from @floating-ui/react for consistency if the pattern is problematic, but only if issues are discovered during testing

🤖 Prompt for AI agents

Fix the TooltipTrigger component to be compatible with React 19's ref handling
changes.

In `src/components/ui/Tooltip/fragments/TooltipTrigger.tsx`:
- Replace the direct `(children as any).ref` access with React 19-compatible ref
extraction
- Use `React.isValidElement(children)` to validate the children element
- Extract ref from `children.props.ref` instead of `children.ref`
- Maintain backward compatibility with React 18 by handling both ref locations
- Keep the existing `useMergeRefs` logic intact

Review and verify:
- Check `TabTrigger.tsx` and `TabNavLink.tsx` for any similar ref access issues
- Ensure custom ref composition patterns work with React 19

Phase 2: Update Package Dependencies for React 19 Support

This phase formally declares React 19 support in the package configuration and updates related dependencies.

Task 1: Update Peer Dependencies

Expand the React version range to include React 19 while maintaining React 18 support.

• In root package.json, update peerDependencies to accept both React 18 and 19: "react": "^18.2.0 || ^19.0.0" and "react-dom": "^18.2.0 || ^19.0.0"
• Keep the main dependencies section on React ^18.2.0 for now (this is what's used for development and testing)
• This allows the library to be installed with either React 18 or React 19 in consuming projects

Task 2: Update TypeScript Type Definitions

Ensure TypeScript types support both React versions.

• Update @types/react and @types/react-dom in devDependencies to versions that support React 19 types (19.x)
• Verify that existing component type definitions don't rely on React 18-specific type structures
• The existing forwardRef patterns should work with updated types since they follow standard patterns

Task 3: Update Floating UI Dependencies

Verify and update floating-ui React package if needed for React 19 compatibility.

• Check if @floating-ui/react version ^0.27.4 supports React 19, and update to latest stable version if needed
• The useMergeRefs utility from this package is used extensively, so ensuring compatibility is critical
• Review release notes to confirm no breaking changes affect the current usage patterns

🤖 Prompt for AI agents

Update package dependencies to formally support React 19 alongside React 18.

In root `package.json`:
- Update `peerDependencies` for both `react` and `react-dom` to: `"^18.2.0 ||
^19.0.0"`
- Update `@types/react` and `@types/react-dom` in `devDependencies` to version
19.x
- Check and update `@floating-ui/react` to the latest version that supports
React 19 if needed
- Keep main `dependencies` on React ^18.2.0 for development

Verify no type errors are introduced by the updated React type definitions.

Phase 3: Validation and Documentation

This phase ensures the changes work correctly and users understand the React version support.

Task 1: Test with React 19

Verify the library works correctly with React 19.

• Run the docs site (which uses React 19) and confirm the error no longer appears
• Test TooltipTrigger component specifically with various ref scenarios (forwarded refs, callback refs, no refs)
• Verify all tooltip interactions work correctly (hover, click, keyboard navigation)
• Run existing test suite to ensure no regressions

Task 2: Test React 18 Compatibility

Ensure changes remain backward compatible with React 18.

• Run the library's test suite with React 18 (current dev dependencies)
• Verify TooltipTrigger ref handling works the same way as before with React 18
• Test that other components using forwardRef and useMergeRefs continue to work

Task 3: Update Documentation

Document React version support for users.

• Add a note to README.md or relevant documentation indicating the library supports React 18.2+ and React 19
• If there's a migration guide or changelog, document the React 19 compatibility addition
• Note that users on either React version can use the library without changes

🤖 Prompt for AI agents

Validate the React 19 compatibility changes and update documentation.

Testing:
- Run the docs site with React 19 and verify the TooltipTrigger error is
resolved
- Test tooltip functionality with various ref scenarios (forwarded, callback,
none)
- Run the full test suite with both React 18 and React 19
- Verify no regressions in ref handling across all components

Documentation:
- Update README.md to indicate support for React 18.2+ and React 19
- Add changelog entry documenting React 19 compatibility
- Note that no user changes are required for either React version

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Fix the TooltipTrigger component to be compatible with React 19's ref handling
changes.

In `src/components/ui/Tooltip/fragments/TooltipTrigger.tsx`:
- Replace the direct `(children as any).ref` access with React 19-compatible ref
extraction
- Use `React.isValidElement(children)` to validate the children element
- Extract ref from `children.props.ref` instead of `children.ref`
- Maintain backward compatibility with React 18 by handling both ref locations
- Keep the existing `useMergeRefs` logic intact

Review and verify:
- Check `TabTrigger.tsx` and `TabNavLink.tsx` for any similar ref access issues
- Ensure custom ref composition patterns work with React 19
===============================================================================

Task: 2

Update package dependencies to formally support React 19 alongside React 18.

In root `package.json`:
- Update `peerDependencies` for both `react` and `react-dom` to: `"^18.2.0 ||
^19.0.0"`
- Update `@types/react` and `@types/react-dom` in `devDependencies` to version
19.x
- Check and update `@floating-ui/react` to the latest version that supports
React 19 if needed
- Keep main `dependencies` on React ^18.2.0 for development

Verify no type errors are introduced by the updated React type definitions.
===============================================================================

Task: 3

Validate the React 19 compatibility changes and update documentation.

Testing:
- Run the docs site with React 19 and verify the TooltipTrigger error is
resolved
- Test tooltip functionality with various ref scenarios (forwarded, callback,
none)
- Run the full test suite with both React 18 and React 19
- Verify no regressions in ref handling across all components

Documentation:
- Update README.md to indicate support for React 18.2+ and React 19
- Add changelog entry documenting React 19 compatibility
- Note that no user changes are required for either React version

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!