[austincalvelage]

Description

Mosaic still supports React 18, where a function component that isn't wrapped in React.forwardRef drops a consumer's ref and logs a warning. Twenty exported Mosaic parts did this, so a ref passed to them came back null.

Every part that renders through useRender now forwards its ref to the rendered element, along with the component Menu.Separator. Where a part already held internal refs (Select.Option, Tabs.List, Accordion.Root, Accordion.Trigger), the consumer ref is merged in alongside them, so roving focus and anchoring keep working.

A new mosaic/forward-ref-parts lint rule fails when an exported part renders through useRender without forwardRef, or wraps itself in forwardRef but never passes the ref to useRender. docs/headless.md notes the requirement.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Oct 28, 2026 11:16pm UTC
swingset	Ready	Preview	Oct 28, 2026 11:16pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 4a794d9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Caution

Review failed

The pull request is closed.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@10505

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@10505

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@10505

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@10505

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10505

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10505

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10505

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@10505

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10505

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10505

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10505

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@10505

@clerk/express

npm i https://pkg.pr.new/@clerk/express@10505

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@10505

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@10505

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@10505

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10505

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@10505

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@10505

@clerk/react

npm i https://pkg.pr.new/@clerk/react@10505

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@10505

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@10505

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@10505

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@10505

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@10505

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@10505

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@10505

commit: 4a794d9