refactor(ui): type Mosaic render callbacks from MosaicComponentProps by alexcarpenter · Pull Request #9302 · clerk/javascript

alexcarpenter · 2026-07-31T12:28:50Z

Description

MosaicComponentProps omitted the native color from a component's own props, but still typed render with the headless primitive's props:

export type MosaicComponentProps<Tag> = Omit<React.ComponentPropsWithRef<Tag>, 'color'> & {
  render?: RenderPropOrElement<Tag>; // callback still hands back color?: string
};

So a render callback received a color?: string that collided with a component's color variant, and each call site worked around it by destructuring the prop away before spreading:

trigger={({ color: _nativeColor, ...props }) => <Button variant='outline' {...props} />}

render is now typed from the same color-omitted props the component itself accepts, so the omission is inherited everywhere instead of being reapplied per call site. Widening back to the primitive's props stays safe (dropping an optional prop leaves the callback assignable), so these still compose with the headless parts, which continue to mirror Base UI.

Menu's trigger props and Dialog's trigger now derive from MosaicComponentProps rather than re-deriving from the headless types, which is what routed them around the contract in the first place. Both workarounds are removed.

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

MosaicComponentProps omitted the native color from a component's own props but still typed render with the headless primitive's props, so a render callback handed back a color?: string that collided with a color variant. Every call site worked around it by destructuring the prop away. Type render from MosaicElementProps so the omission is inherited everywhere, and derive Menu's trigger props and Dialog's trigger from MosaicComponentProps rather than re-deriving them from the headless types. Widening back to the primitive's props stays safe, so the callbacks remain assignable to headless.

changeset-bot · 2026-07-31T12:28:56Z

🦋 Changeset detected

Latest commit: 716a4ee

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

vercel · 2026-07-31T12:28:57Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Jul 31, 2026 8:42pm
swingset	Ready	Preview	Jul 31, 2026 8:42pm

pkg-pr-new · 2026-07-31T12:31:42Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 716a4ee

github-actions · 2026-07-31T12:32:24Z

API Changes Report

Generated by Break Check on 2026-07-31T20:44:13.572Z

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 716a4ee.}

coderabbitai · 2026-07-31T12:35:34Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: bbdfcbe9-9e15-415f-bb55-f82ba694c63c

📥 Commits

Reviewing files that changed from the base of the PR and between 57f1ce7 and 716a4ee.

📒 Files selected for processing (10)

packages/headless/src/utils/index.ts
packages/headless/src/utils/use-render.test-d.ts
packages/headless/src/utils/use-render.tsx
packages/swingset/src/stories/dialog.component.stories.tsx
packages/ui/src/mosaic/components/button/button.tsx
packages/ui/src/mosaic/components/dialog.tsx
packages/ui/src/mosaic/components/item/item.tsx
packages/ui/src/mosaic/components/tabs.tsx
packages/ui/src/mosaic/primitives/box.tsx
packages/ui/src/mosaic/props.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)

🚧 Files skipped from review as they are similar to previous changes (1)

packages/ui/src/mosaic/components/dialog.tsx

📝 Walkthrough

Walkthrough

The PR adds a shared RenderProps contract and updates ComponentProps and MosaicComponentProps. It exports prop types for dialog and tabs parts. It updates menu, dialog, item, button, and box render contracts. Trigger implementations now forward complete render props. Type tests cover tag-independent render props and native property handling.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

clerk/javascript#9252: Modifies the same Mosaic menu trigger implementation.
clerk/javascript#9267: Modifies shared Mosaic prop typing.
clerk/javascript#9296: Continues the Mosaic render prop and MosaicComponentProps changes.

Suggested reviewers: austincalvelage

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main refactoring of Mosaic render callback typing.
Description check	✅ Passed	The description directly explains the color typing issue, the refactoring, and the affected Mosaic trigger contracts.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

# Conflicts: # packages/ui/src/mosaic/components/menu/menu.tsx # packages/ui/src/mosaic/props.ts

…entProps Tabs and Dialog took their parts' props straight from the headless primitives, so their render callbacks still handed back the native color?: string that collides with a color variant. Add MosaicPartProps to re-expose a headless part's props the Mosaic way: the part's own additions kept, color and render swapped for Mosaic's. Item redeclared render as RenderProp<React.HTMLAttributes<HTMLElement>> after omitting the inherited one. Nothing depended on the widening: the inherited render types the link case its docblock and tests already cover, so drop the override.

The inherited render pins ref to the default tag's HTMLDivElement, which a callback cannot spread onto the <a> or <button> a row renders. Restore the override and say why it exists, so the next reader doesn't take it for redundant.

`RenderPropOrElement<Tag>` pinned a `render` callback's props to the part's default tag, so every Mosaic component worked around the same two problems: a `ref` that would not spread onto a different element, and the non-standard `color` attribute colliding with a `color` variant. Splits the two contracts at the source. `ComponentProps<Tag>` stays pinned to the tag for the component's own props; the new `RenderProps` is tag-agnostic, matching Base UI's `HTMLProps`. Both drop `color`. Deletes the workarounds this made unnecessary: `MosaicPartProps`, Item's redeclared `render`, box's hand-rolled render prop, and the last `color` destructure in swingset.

github-actions Bot added the ui label Jul 31, 2026

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 12:29 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 12:31 View deployment

alexcarpenter requested review from austincalvelage and maxyinger July 31, 2026 15:25

maxyinger approved these changes Jul 31, 2026

View reviewed changes

alexcarpenter added 2 commits July 31, 2026 15:23

Merge remote-tracking branch 'origin/main' into carp/mosaic-render-props

e52caa0

# Conflicts: # packages/ui/src/mosaic/components/menu/menu.tsx # packages/ui/src/mosaic/props.ts

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 19:53 View deployment

vercel Bot had a problem deploying to Preview – swingset July 31, 2026 19:54 Failure

fix(ui): restore Item's ref-less render prop

57f1ce7

The inherited render pins ref to the default tag's HTMLDivElement, which a callback cannot spread onto the <a> or <button> a row renders. Restore the override and say why it exists, so the next reader doesn't take it for redundant.

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 20:06 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 20:08 View deployment

vercel Bot deployed to Preview – clerk-js-sandbox July 31, 2026 20:41 View deployment

vercel Bot deployed to Preview – swingset July 31, 2026 20:42 View deployment

coderabbitai Bot mentioned this pull request Jul 31, 2026

feat(ui): Add a Mosaic scroll area as StyleX atoms #9311

Open

9 tasks

alexcarpenter merged commit ec24507 into main Jul 31, 2026
51 checks passed

alexcarpenter deleted the carp/mosaic-render-props branch July 31, 2026 21:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(ui): type Mosaic render callbacks from MosaicComponentProps - #9302

refactor(ui): type Mosaic render callbacks from MosaicComponentProps#9302
alexcarpenter merged 5 commits into
mainfrom
carp/mosaic-render-props

alexcarpenter commented Jul 31, 2026

Uh oh!

changeset-bot Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 31, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 31, 2026 •

edited

Loading

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

alexcarpenter commented Jul 31, 2026

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

No API Changes Detected

Uh oh!

coderabbitai Bot commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Jul 31, 2026 •

edited

Loading

vercel Bot commented Jul 31, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 31, 2026 •

edited

Loading

github-actions Bot commented Jul 31, 2026 •

edited

Loading

coderabbitai Bot commented Jul 31, 2026 •

edited

Loading