@clerk/mosaic
Getting started
@clerk/mosaic provides Clerk's experimental next-generation React components.
This package lets you preview and provide feedback on Clerk's next generation of components.
When stable, components will move to be exported through the regular packages.
:construction: We reserve the right to make breaking changes in minors, please pin your version.
Prerequisites
- Node.js
>=20.9.0or later - A supported React-based Clerk SDK that renders a
ClerkProvider@clerk/reactversion 6 or later@clerk/nextjsversion 7 or later- Other React-based Clerk SDKs may also work, but are currently untested
- React 18 or 19
Installation
npm install --save-exact @clerk/mosaic
pnpm add --save-exact @clerk/mosaic
yarn add --exact @clerk/mosaic
Usage
Import the stylesheet and render Mosaic components beneath the SDK ClerkProvider:
import { ClerkProvider } from '@clerk/react';
import { UserButton } from '@clerk/mosaic';
import '@clerk/mosaic/styles.css';
export function App({ children }) {
return (
<ClerkProvider publishableKey={process.env.CLERK_PUBLISHABLE_KEY}>
<UserButton />
{children}
</ClerkProvider>
);
}
If you want to use custom CSS to theme the components, instead import the stylesheet into a cascade layer:
@import '@clerk/mosaic/styles.css' layer(components);
This ensures your unlayered custom CSS takes priority. Expect more documentation on custom theming soon.
Troubleshooting
A Clerk hook says it can only be used within <ClerkProvider />
Mosaic and your Clerk framework SDK must resolve the same copy of @clerk/shared. If <ClerkProvider /> is present but you still see this error, deduplicate your dependencies:
npm dedupe
pnpm dedupe
yarn dedupe @clerk/shared
Check the installed versions:
npm ls @clerk/shared
pnpm why @clerk/shared
yarn why @clerk/shared
If multiple versions remain, the supported ranges are likely incompatible. Update Mosaic and your Clerk framework SDK to the latest versions, then deduplicate again.
License
This project is licensed under the MIT license.
See LICENSE for more information.