Clerk Elements

Clerk Elements Skill

Build completely custom authentication UIs using Clerk's headless UI primitives.

When to Use

Use this skill when:

• User wants custom-styled auth pages (not default Clerk components)
• Need explicit social buttons (GitHub, Google) with custom layout
• Want redirect mode instead of popup for OAuth
• Building auth that matches an existing design system
• Implementing OTP inputs with custom styling
• Creating multi-step auth flows with custom UI

Important Notice

Clerk Elements is no longer in active development. Clerk is building a replacement with a different approach. However, it still works and is the only way to build fully custom auth UIs with Clerk.

Prerequisites

• Next.js App Router (required - no other framework support)
• Clerk Core 2 or later
• TypeScript config: Set moduleResolution: "bundler" in tsconfig.json

pnpm add @clerk/elements

Package Structure

// Common components (shared between sign-in/sign-up)
import * as Clerk from "@clerk/elements/common";

// Sign-in specific components
import * as SignIn from "@clerk/elements/sign-in";

// Sign-up specific components
import * as SignUp from "@clerk/elements/sign-up";

Component Reference

Common Components (@clerk/elements/common)

<Clerk.Connection>

Renders OAuth/social authentication buttons.

<Clerk.Connection name="google">
  <Clerk.Icon /> Sign in with Google
</Clerk.Connection>

// With asChild for custom button
<Clerk.Connection name="github" asChild>
  <Button variant="outline">
    <GitHubIcon /> GitHub
  </Button>
</Clerk.Connection>

Important: Providers must be enabled in Clerk Dashboard → User & Authentication → Social connections.

<Clerk.Field>

Wraps form fields with automatic label association.

| Prop | Type | Description | | ------------ | -------- | ---------------------------------------- | ------- | --------- | ------ | ------- | | name | string | Field identifier (see table below) | | alwaysShow | boolean | Force rendering regardless of flow state | | children | function | Access field state: 'success' | 'error' | 'warning' | 'info' | 'idle' |

Field Names:

<Clerk.Field name="emailAddress">
  {(state) => (
    <>
      <Clerk.Label>Email</Clerk.Label>
      <Clerk.Input type="email" />
      <Clerk.FieldError />
      {state === "error" && <span className="text-red-500">!</span>}
    </>
  )}
</Clerk.Field>

<Clerk.Input>

Form input with automatic field binding.

Data Attributes (for CSS):

• data-valid / data-invalid
• data-state="success|error|warning|info|idle"
• data-has-value

// Standard input
<Clerk.Input type="email" />

// With custom component
<Clerk.Input type="email" asChild>
  <CustomInput className="my-input" />
</Clerk.Input>

// Password with validation
<Clerk.Input type="password" validatePassword />

<Clerk.Input type="otp">

Specialized OTP input with segmented display.

<Clerk.Input
  type="otp"
  length={6}
  autoSubmit
  render={({ value, status }) => (
    <span data-status={status}>{value || <span className="placeholder">-</span>}</span>
  )}
/>

Status values: 'cursor', 'selected', 'hovered', 'none'

<Clerk.Label>

Accessible label automatically associated with sibling input.

<Clerk.Field name="email">
  <Clerk.Label>Email Address</Clerk.Label>
  <Clerk.Input type="email" />
</Clerk.Field>

<Clerk.FieldError>

Displays validation errors for the current field.

// Simple
<Clerk.FieldError />

// Custom rendering
<Clerk.FieldError>
  {({ message, code }) => (
    <span className="error" data-code={code}>{message}</span>
  )}
</Clerk.FieldError>

<Clerk.GlobalError>

Displays API errors not tied to specific fields.

<Clerk.GlobalError>{({ message }) => <div className="alert">{message}</div>}</Clerk.GlobalError>

<Clerk.Loading>

Access loading states for conditional UI.

Scope values:

• undefined or omitted - Global loading state
• 'provider:google' - Specific OAuth provider
• 'step:start' - Specific step
• 'submit' - Form submission

<Clerk.Loading>
  {(isGlobalLoading) => (
    <Button disabled={isGlobalLoading}>
      {isGlobalLoading ? <Spinner /> : 'Continue'}
    </Button>
  )}
</Clerk.Loading>

// Provider-specific
<Clerk.Loading scope="provider:google">
  {(isLoading) => isLoading ? <Spinner /> : <GoogleIcon />}
</Clerk.Loading>

<Clerk.Icon>

Renders OAuth provider logos. Must be inside <Clerk.Connection>.

<Clerk.Connection name="github">
  <Clerk.Icon className="w-4 h-4" />
  GitHub
</Clerk.Connection>

<Clerk.Link>

Navigation between sign-in and sign-up flows.

<Clerk.Link navigate="sign-up">Don't have an account? Sign up</Clerk.Link>

Sign-In Components (@clerk/elements/sign-in)

<SignIn.Root>

Root wrapper managing sign-in state.

<SignIn.Root>
  {/* Steps go here */}
</SignIn.Root>

// Modal mode (no URL changes)
<SignIn.Root routing="virtual">
  {/* ... */}
</SignIn.Root>

<SignIn.Step>

Conditionally renders based on auth progress.

<SignIn.Root>
  <SignIn.Step name="start">{/* Initial form */}</SignIn.Step>

  <SignIn.Step name="verifications">{/* Verification UI */}</SignIn.Step>
</SignIn.Root>

<SignIn.Strategy>

Conditionally renders for specific verification methods.

<SignIn.Step name="verifications">
  <SignIn.Strategy name="email_code">
    <h2>Check your email</h2>
    <p>
      We sent a code to <SignIn.SafeIdentifier />
    </p>
    <Clerk.Field name="code">
      <Clerk.Label>Code</Clerk.Label>
      <Clerk.Input type="otp" />
      <Clerk.FieldError />
    </Clerk.Field>
    <SignIn.Action submit>Verify</SignIn.Action>
  </SignIn.Strategy>

  <SignIn.Strategy name="password">
    <Clerk.Field name="password">
      <Clerk.Label>Password</Clerk.Label>
      <Clerk.Input type="password" />
      <Clerk.FieldError />
    </Clerk.Field>
    <SignIn.Action submit>Sign In</SignIn.Action>
  </SignIn.Strategy>
</SignIn.Step>

<SignIn.Action>

Form actions (submit, navigate, resend).

// Submit
<SignIn.Action submit>Continue</SignIn.Action>

// Navigate
<SignIn.Action navigate="forgot-password">
  Forgot password?
</SignIn.Action>

// Resend with cooldown
<SignIn.Action
  resend
  fallback={({ resendableAfter }) => (
    <span>Resend in {resendableAfter}s</span>
  )}
>
  Resend code
</SignIn.Action>

<SignIn.SafeIdentifier>

Displays masked user identifier (e.g., j***@example.com).

<p>
  We sent a code to <SignIn.SafeIdentifier />
</p>

<SignIn.SupportedStrategy>

Button to switch verification strategy.

<SignIn.Step name="choose-strategy">
  <SignIn.SupportedStrategy name="email_code">Email me a code</SignIn.SupportedStrategy>
  <SignIn.SupportedStrategy name="password">Use password</SignIn.SupportedStrategy>
</SignIn.Step>

<SignIn.Passkey>

Triggers passkey autofill.

<SignIn.Step name="start">
  <SignIn.Passkey>Sign in with passkey</SignIn.Passkey>
</SignIn.Step>

Sign-Up Components (@clerk/elements/sign-up)

<SignUp.Root>

Root wrapper for sign-up flows.

<SignUp.Step>

Conditionally renders sign-up stages.

<SignUp.Strategy>

Verification method rendering.

<SignUp.Action>

Form actions (same API as SignIn.Action).

<SignUp.Captcha>

Cloudflare Turnstile CAPTCHA widget.

<SignUp.Step name="start">
  {/* Fields... */}
  <SignUp.Captcha />
  <SignUp.Action submit>Create Account</SignUp.Action>
</SignUp.Step>

Flow Patterns

Complete Sign-In Flow

"use client";

import * as Clerk from "@clerk/elements/common";
import * as SignIn from "@clerk/elements/sign-in";

export default function SignInPage() {
  return (
    <SignIn.Root>
      <Clerk.Loading>
        {(isGlobalLoading) => (
          <>
            {/* Step 1: Start */}
            <SignIn.Step name="start">
              <h1>Sign In</h1>

              <Clerk.GlobalError />

              {/* Social Buttons */}
              <div className="social-buttons">
                <Clerk.Connection name="google" asChild>
                  <button disabled={isGlobalLoading}>
                    <Clerk.Loading scope="provider:google">
                      {(isLoading) => (isLoading ? "..." : "Google")}
                    </Clerk.Loading>
                  </button>
                </Clerk.Connection>

                <Clerk.Connection name="github" asChild>
                  <button disabled={isGlobalLoading}>
                    <Clerk.Loading scope="provider:github">
                      {(isLoading) => (isLoading ? "..." : "GitHub")}
                    </Clerk.Loading>
                  </button>
                </Clerk.Connection>
              </div>

              <div className="divider">or</div>

              {/* Email Input */}
              <Clerk.Field name="identifier">
                <Clerk.Label>Email</Clerk.Label>
                <Clerk.Input type="email" />
                <Clerk.FieldError />
              </Clerk.Field>

              <SignIn.Action submit disabled={isGlobalLoading}>
                Continue
              </SignIn.Action>

              <Clerk.Link navigate="sign-up">Don't have an account? Sign up</Clerk.Link>
            </SignIn.Step>

            {/* Step 2: Verifications */}
            <SignIn.Step name="verifications">
              {/* Email Code */}
              <SignIn.Strategy name="email_code">
                <h1>Check your email</h1>
                <p>
                  We sent a code to <SignIn.SafeIdentifier />
                </p>

                <Clerk.Field name="code">
                  <Clerk.Label>Verification Code</Clerk.Label>
                  <Clerk.Input type="otp" autoSubmit />
                  <Clerk.FieldError />
                </Clerk.Field>

                <SignIn.Action submit>Verify</SignIn.Action>

                <SignIn.Action
                  resend
                  fallback={({ resendableAfter }) => <span>Resend in {resendableAfter}s</span>}
                >
                  Resend code
                </SignIn.Action>
              </SignIn.Strategy>

              {/* Password */}
              <SignIn.Strategy name="password">
                <h1>Enter password</h1>

                <Clerk.Field name="password">
                  <Clerk.Label>Password</Clerk.Label>
                  <Clerk.Input type="password" />
                  <Clerk.FieldError />
                </Clerk.Field>

                <SignIn.Action submit>Sign In</SignIn.Action>
                <SignIn.Action navigate="forgot-password">Forgot password?</SignIn.Action>
              </SignIn.Strategy>
            </SignIn.Step>

            {/* Step 3: Choose Strategy (alternative methods) */}
            <SignIn.Step name="choose-strategy">
              <h1>Use another method</h1>

              <SignIn.SupportedStrategy name="email_code">Email me a code</SignIn.SupportedStrategy>

              <SignIn.SupportedStrategy name="password">Use password</SignIn.SupportedStrategy>

              <SignIn.Action navigate="previous">Back</SignIn.Action>
            </SignIn.Step>
          </>
        )}
      </Clerk.Loading>
    </SignIn.Root>
  );
}

Complete Sign-Up Flow

"use client";

import * as Clerk from "@clerk/elements/common";
import * as SignUp from "@clerk/elements/sign-up";

export default function SignUpPage() {
  return (
    <SignUp.Root>
      {/* Step 1: Start */}
      <SignUp.Step name="start">
        <h1>Create Account</h1>

        <Clerk.GlobalError />

        {/* Social */}
        <Clerk.Connection name="google">
          <Clerk.Icon /> Google
        </Clerk.Connection>

        <Clerk.Connection name="github">
          <Clerk.Icon /> GitHub
        </Clerk.Connection>

        <div className="divider">or</div>

        {/* Fields */}
        <Clerk.Field name="emailAddress">
          <Clerk.Label>Email</Clerk.Label>
          <Clerk.Input type="email" />
          <Clerk.FieldError />
        </Clerk.Field>

        <Clerk.Field name="password">
          <Clerk.Label>Password</Clerk.Label>
          <Clerk.Input type="password" validatePassword />
          <Clerk.FieldError />
        </Clerk.Field>

        <SignUp.Captcha />

        <SignUp.Action submit>Create Account</SignUp.Action>

        <Clerk.Link navigate="sign-in">Already have an account? Sign in</Clerk.Link>
      </SignUp.Step>

      {/* Step 2: Continue (extra fields) */}
      <SignUp.Step name="continue">
        <h1>Complete Profile</h1>

        <Clerk.Field name="username">
          <Clerk.Label>Username</Clerk.Label>
          <Clerk.Input />
          <Clerk.FieldError />
        </Clerk.Field>

        <SignUp.Action submit>Continue</SignUp.Action>
      </SignUp.Step>

      {/* Step 3: Verifications */}
      <SignUp.Step name="verifications">
        <SignUp.Strategy name="email_code">
          <h1>Verify Email</h1>

          <Clerk.Field name="code">
            <Clerk.Label>Code</Clerk.Label>
            <Clerk.Input type="otp" />
            <Clerk.FieldError />
          </Clerk.Field>

          <SignUp.Action submit>Verify</SignUp.Action>

          <SignUp.Action resend>Resend</SignUp.Action>
        </SignUp.Strategy>
      </SignUp.Step>
    </SignUp.Root>
  );
}

Styling Patterns

Tailwind CSS

<Clerk.Field name="email" className="space-y-2">
  <Clerk.Label className="text-sm font-medium">Email</Clerk.Label>
  <Clerk.Input type="email" className="w-full px-3 py-2 border rounded-md focus:ring-2" />
  <Clerk.FieldError className="text-sm text-red-500" />
</Clerk.Field>

CSS-in-JS (styled-jsx)

<Clerk.Field name="email">
  <Clerk.Label>Email</Clerk.Label>
  <Clerk.Input type="email" />
  <style jsx>{`
    :global([data-invalid]) {
      border-color: var(--error);
    }
  `}</style>
</Clerk.Field>

With Component Libraries (asChild)

import { Input } from '@/components/ui/input'
import { Button } from '@/components/ui/button'

<Clerk.Input type="email" asChild>
  <Input placeholder="Enter email" />
</Clerk.Input>

<SignIn.Action submit asChild>
  <Button>Continue</Button>
</SignIn.Action>

OAuth Redirect vs Popup

Clerk Elements uses redirect mode by default, solving the narrow popup issue. The OAuth flow:

1. User clicks social button
2. Full-page redirect to provider (Google, GitHub, etc.)
3. Provider authenticates user
4. Redirect back to your app

This works better on mobile than the popup mode used by pre-built components.

Dashboard Configuration

Enable Social Providers

1. Go to Clerk Dashboard
2. Navigate to User & Authentication → Social connections
3. Enable desired providers (Google, GitHub, etc.)
4. Configure OAuth credentials for each provider

Required Settings

For email code verification:

• User & Authentication → Email, phone, username → Enable Email address
• Enable Email verification code as verification method

File Structure

app/
├── sign-in/
│   └── [[...sign-in]]/
│       └── page.tsx      # Custom sign-in with Elements
├── sign-up/
│   └── [[...sign-up]]/
│       └── page.tsx      # Custom sign-up with Elements

The [[...sign-in]] catch-all route handles all sign-in steps at /sign-in/*.

TypeScript Configuration

Ensure tsconfig.json has:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

Documentation Links

• Overview
• Sign-In Guide
• Sign-Up Guide
• Common Components
• SignIn Components
• SignUp Components
• shadcn/ui Examples
• Clerk Dashboard

Troubleshooting