feat(headless): add useRender hook alongside renderElement

[alexcarpenter]

Why

renderElement (function) → useRender (hook). Wins:

1. render-as-element. Today every override must be a function wrapper. Now pass the element directly.

// before
<Trigger render={props => <Link {...props} href="/home" />} />
// after
<Trigger render={<Link href="/home" />} />

2. ref merging moves inside. Drop the per-call-site useMergeRefs.

// before
const combinedRef = useMergeRefs([popupRef, refs.setFloating, ref]);
if (!mounted) return null;
return renderElement({ defaultTagName: 'div', render, props: { ref: combinedRef, ...rest } });
// after
const el = useRender({ defaultTagName: 'div', render, enabled: mounted, ref: [popupRef, refs.setFloating, ref], props: rest });
if (!el) return null;
return el;

3. Mosaic: one path, no cast.

// before
if (render) return renderElement({ defaultTagName: 'h2', render, props: { ref, ...root, ...rest } as Record<string, unknown> });
return <h2 ref={ref} {...root} {...rest} />;
// after
return useRender({ defaultTagName: 'h2', render, ref, props: { ...root, ...rest } });

Also aligns with base-ui (swingset already uses real base-ui useRender).

Scope

PR1 of a phased series. Adds useRender (own utils/use-render.tsx), keeps renderElement exported for the rest of the migration. Migrates Mosaic Box/Heading/Text + dialog-trigger/dialog-popup as representative patterns. Follow-ups convert remaining ~60 primitives by family; final PR deletes renderElement.

Reuses Clerk's mergeProps + useMergeRefs (@floating-ui/react, already a dep). No new runtime dep, no base-ui engine vendored.

Empty changeset: @clerk/headless private, migrated Mosaic parts not in @clerk/ui public exports (matches #9208).

Verified

@clerk/headless typecheck + 601 tests pass. @clerk/ui type-check clean.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 23, 2026 9:36pm
swingset	Ready	Preview, Comment	Jul 23, 2026 9:36pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 3445cc3

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]

Warning

Review limit reached

@alexcarpenter, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 33 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: c8d8d2a4-e5f1-40a3-ab41-560b44fd787a

📥 Commits

Reviewing files that changed from the base of the PR and between acef8a1 and 3445cc3.

📒 Files selected for processing (10)

• .changeset/mosaic-use-render.md
• packages/headless/src/primitives/dialog/dialog-popup.tsx
• packages/headless/src/primitives/dialog/dialog-trigger.tsx
• packages/headless/src/utils/index.ts
• packages/headless/src/utils/render-element.tsx
• packages/headless/src/utils/use-render.test.tsx
• packages/headless/src/utils/use-render.tsx
• packages/ui/src/mosaic/components/heading.tsx
• packages/ui/src/mosaic/components/text.tsx
• packages/ui/src/mosaic/primitives/box.tsx

---

_{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@9231

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3445cc3

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-23T21:37:37.717Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 3445cc3.}

[wobsoriano]

clean!