Docs

Clerk Elements (Beta)

Warning

Clerk Elements is currently in beta with support for Next.js App Router. It is not yet recommended for production use.

If you have any feedback, please reach out to beta-elements@clerk.dev or head over to the GitHub Discussion.

Clerk Elements is a library of unstyled, composable components that can be used to build custom UIs on top of Clerk's APIs without having to manage the underlying logic.

Clerk Elements

Why use Clerk Elements?

You should use Clerk Elements if you want a deeper level of control and customization of the styles and layout of your UI while using Clerk's APIs. For example, if the appearance prop does not meet your needs, Clerk Elements might be for you. That said, you can also use Clerk Elements alongside the prebuilt components.

  • Component-first - Make it as easy to build custom UIs with Clerk as it is with Clerk's drop-in prebuilt components. Clerk Elements handles the underlying business logic for you and provides a curated library of components without sacrificing on best practices or features.
  • Unstyled, with a little bit of magic - Use the web platform and best-in-class components for building great authentication flows. Baked-in to the components are little bits of magic, like the fully accessible segmented one-time-passcode (OTP) input, and instant password validation during sign up.

Integrate Clerk Elements into your workflow

Clerk Elements can be integrated into your existing application and workflows. For example, you may want to use Clerk Elements with:

  • Tailwind CSS – If you use Tailwind CSS, you can pass a className prop to most elements that Clerk Elements renders. See the styling guide to learn more.
  • Existing styles or component library – If you have an existing component library that you want to use to build your authentication UIs, Clerk Elements supports composition via an asChild prop. Read the styling guide to learn more.
  • With Clerk's prebuilt components - Continue using Clerk's prebuilt components while customizing the flows you care most about.

Getting started

Clerk Elements currently only works with Next.js App Router and Clerk Core 2. As it gets closer to a stable release, support for additional frameworks will be added. If your Next.js application is already using Clerk, make sure to upgrade to Core 2. If you're starting from scratch, follow the Next.js quickstart before proceeding.

To get started, install the Clerk Elements package:

terminal
npm install @clerk/elements
terminal
yarn add @clerk/elements
terminal
pnpm add @clerk/elements

Important

If your project uses TypeScript, make sure that your moduleResolution in tsconfig.json is set to bundler. Otherwise, you might run into issues with resolving TypeScript types from Clerk Elements.

Once you have your project set up, you can start building custom UIs with Clerk Elements using Clerk's guides and examples. For example, to use Clerk Elements to build a custom sign-in flow, you can explore:

Note

With the beta release, only sign-up and sign-in flows are supported. Support for building the rest of Clerk's prebuilt components with Elements is actively being worked on.

Feedback

What did you think of this content?

Last updated on