or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

backend-api-client.mdclient-components.mdclient-hooks.mderror-handling.mdindex.mdmiddleware-and-route-protection.mdserver-auth-app-router.mdserver-auth-pages-router.mdsetup-and-provider.mdwebhooks.md
tile.json

client-components.mddocs/

Client Components

Pre-built, customizable UI components for authentication flows, user management, and organization management. All components are client components and use the 'use client' directive.

Capabilities

Authentication UI Components

SignIn Component

Renders a complete sign-in form with support for email, phone, username, and social OAuth providers.

/**
 * Renders the sign-in form component
 * @param props - SignIn component props
 * @returns Sign-in form JSX element
 */
function SignIn(props: SignInProps): JSX.Element;

interface SignInProps {
  /** Routing strategy: 'path' (URL-based) or 'virtual' (state-based) */
  routing?: 'path' | 'virtual';
  /** Path where component is mounted (required when routing='path') */
  path?: string;
  /** URL to redirect after successful sign-in */
  afterSignInUrl?: string;
  /** URL to redirect after successful sign-up (when switching to sign-up) */
  afterSignUpUrl?: string;
  /** URL to redirect to (overrides other redirect URLs) */
  redirectUrl?: string;
  /** Customization options for appearance */
  appearance?: Appearance;
  /** Additional sign-in options */
  signUpUrl?: string;
}

Usage Example:

import { SignIn } from '@clerk/nextjs';

// Embedded in a route
export default function SignInPage() {
  return <SignIn routing="path" path="/sign-in" />;
}

// With custom redirect
export default function SignInPage() {
  return <SignIn afterSignInUrl="/dashboard" signUpUrl="/sign-up" />;
}

SignUp Component

Renders a complete sign-up form with support for email, phone, username, and social OAuth providers.

/**
 * Renders the sign-up form component
 * @param props - SignUp component props
 * @returns Sign-up form JSX element
 */
function SignUp(props: SignUpProps): JSX.Element;

interface SignUpProps {
  /** Routing strategy: 'path' (URL-based) or 'virtual' (state-based) */
  routing?: 'path' | 'virtual';
  /** Path where component is mounted (required when routing='path') */
  path?: string;
  /** URL to redirect after successful sign-up */
  afterSignUpUrl?: string;
  /** URL to redirect after successful sign-in (when switching to sign-in) */
  afterSignInUrl?: string;
  /** URL to redirect to (overrides other redirect URLs) */
  redirectUrl?: string;
  /** Customization options for appearance */
  appearance?: Appearance;
  /** Additional sign-up options */
  signInUrl?: string;
}

Usage Example:

import { SignUp } from '@clerk/nextjs';

export default function SignUpPage() {
  return <SignUp routing="path" path="/sign-up" afterSignUpUrl="/onboarding" />;
}

User Management Components

UserButton Component

Renders a user button with a dropdown menu for account management, including profile, settings, and sign-out options.

/**
 * Renders the user button with dropdown menu
 * @param props - UserButton component props
 * @returns User button JSX element
 */
function UserButton(props: UserButtonProps): JSX.Element;

interface UserButtonProps {
  /** Customization options for appearance */
  appearance?: Appearance;
  /** Show user name next to avatar */
  showName?: boolean;
  /** URL to navigate to when viewing user profile */
  userProfileUrl?: string;
  /** Additional user button options */
  afterSignOutUrl?: string;
}

Usage Example:

import { UserButton } from '@clerk/nextjs';

export default function Header() {
  return (
    <header>
      <nav>
        <UserButton afterSignOutUrl="/" />
      </nav>
    </header>
  );
}

UserProfile Component

Renders a full-page user profile management interface with support for custom pages.

/**
 * Renders the user profile management component
 * Supports custom pages via UserProfile.Page
 * @param props - UserProfile component props
 * @returns User profile JSX element
 */
function UserProfile(props: UserProfileProps): JSX.Element;

interface UserProfileProps {
  /** Routing strategy: 'path' (URL-based) or 'virtual' (state-based) */
  routing?: 'path' | 'virtual';
  /** Path where component is mounted (required when routing='path') */
  path?: string;
  /** Customization options for appearance */
  appearance?: Appearance;
  /** Additional profile options */
  children?: React.ReactNode;
}

// Custom page component
UserProfile.Page: React.ComponentType<{
  label: string;
  url: string;
  children: React.ReactNode;
}>;

Usage Example:

import { UserProfile } from '@clerk/nextjs';

export default function ProfilePage() {
  return (
    <UserProfile routing="path" path="/user-profile">
      <UserProfile.Page label="Custom Settings" url="custom-settings">
        <div>Custom settings content</div>
      </UserProfile.Page>
    </UserProfile>
  );
}

UserAvatar Component

Renders the user's avatar image.

/**
 * Renders the user avatar
 * @param props - UserAvatar component props
 * @returns User avatar JSX element
 */
function UserAvatar(props: UserAvatarProps): JSX.Element;

interface UserAvatarProps {
  /** Size of the avatar */
  size?: number;
}

Organization Management Components

OrganizationSwitcher Component

Renders a dropdown for switching between organizations and creating new ones.

/**
 * Renders the organization switcher dropdown
 * @param props - OrganizationSwitcher component props
 * @returns Organization switcher JSX element
 */
function OrganizationSwitcher(props: OrganizationSwitcherProps): JSX.Element;

interface OrganizationSwitcherProps {
  /** Customization options for appearance */
  appearance?: Appearance;
  /** Hide personal workspace option */
  hidePersonal?: boolean;
  /** URL to navigate after creating organization */
  afterCreateOrganizationUrl?: string;
  /** URL to navigate after selecting organization */
  afterSelectOrganizationUrl?: string;
  /** URL to navigate to organization profile */
  organizationProfileUrl?: string;
  /** URL to create new organization */
  createOrganizationUrl?: string;
}

Usage Example:

import { OrganizationSwitcher } from '@clerk/nextjs';

export default function Header() {
  return (
    <header>
      <OrganizationSwitcher afterSelectOrganizationUrl="/dashboard" />
    </header>
  );
}

OrganizationProfile Component

Renders a full-page organization profile management interface with support for custom pages.

/**
 * Renders the organization profile management component
 * Supports custom pages via OrganizationProfile.Page
 * @param props - OrganizationProfile component props
 * @returns Organization profile JSX element
 */
function OrganizationProfile(props: OrganizationProfileProps): JSX.Element;

interface OrganizationProfileProps {
  /** Routing strategy: 'path' (URL-based) or 'virtual' (state-based) */
  routing?: 'path' | 'virtual';
  /** Path where component is mounted (required when routing='path') */
  path?: string;
  /** Customization options for appearance */
  appearance?: Appearance;
  /** Additional profile options */
  children?: React.ReactNode;
}

// Custom page component
OrganizationProfile.Page: React.ComponentType<{
  label: string;
  url: string;
  children: React.ReactNode;
}>;

OrganizationList Component

Renders a list of organizations with options to create or join organizations.

/**
 * Renders the organization list component
 * @param props - OrganizationList component props
 * @returns Organization list JSX element
 */
function OrganizationList(props: OrganizationListProps): JSX.Element;

interface OrganizationListProps {
  /** Customization options for appearance */
  appearance?: Appearance;
  /** Hide personal workspace option */
  hidePersonal?: boolean;
  /** URL to navigate after creating organization */
  afterCreateOrganizationUrl?: string;
  /** URL to navigate after selecting organization */
  afterSelectOrganizationUrl?: string;
}

CreateOrganization Component

Renders a form for creating a new organization.

/**
 * Renders the create organization form
 * @param props - CreateOrganization component props
 * @returns Create organization form JSX element
 */
function CreateOrganization(props: CreateOrganizationProps): JSX.Element;

interface CreateOrganizationProps {
  /** Routing strategy: 'path' (URL-based) or 'virtual' (state-based) */
  routing?: 'path' | 'virtual';
  /** Path where component is mounted (required when routing='path') */
  path?: string;
  /** Customization options for appearance */
  appearance?: Appearance;
  /** URL to navigate after creating organization */
  afterCreateOrganizationUrl?: string;
}

Button Components

SignInButton Component

Renders a button that opens the sign-in flow.

/**
 * Renders a sign-in button
 * @param props - SignInButton component props
 * @returns Sign-in button JSX element
 */
function SignInButton(props: SignInButtonProps): JSX.Element;

interface SignInButtonProps {
  /** Custom children to render as button content */
  children?: React.ReactNode;
  /** Mode: 'redirect' or 'modal' */
  mode?: 'redirect' | 'modal';
  /** URL to redirect after sign-in */
  afterSignInUrl?: string;
  /** URL to redirect after sign-up */
  afterSignUpUrl?: string;
}

SignUpButton Component

Renders a button that opens the sign-up flow.

/**
 * Renders a sign-up button
 * @param props - SignUpButton component props
 * @returns Sign-up button JSX element
 */
function SignUpButton(props: SignUpButtonProps): JSX.Element;

interface SignUpButtonProps {
  /** Custom children to render as button content */
  children?: React.ReactNode;
  /** Mode: 'redirect' or 'modal' */
  mode?: 'redirect' | 'modal';
  /** URL to redirect after sign-up */
  afterSignUpUrl?: string;
  /** URL to redirect after sign-in */
  afterSignInUrl?: string;
}

SignOutButton Component

Renders a button that signs the user out.

/**
 * Renders a sign-out button
 * @param props - SignOutButton component props
 * @returns Sign-out button JSX element
 */
function SignOutButton(props: SignOutButtonProps): JSX.Element;

interface SignOutButtonProps {
  /** Custom children to render as button content */
  children?: React.ReactNode;
  /** URL to redirect after sign-out */
  afterSignOutUrl?: string;
}

SignInWithMetamaskButton Component

Renders a button for Metamask-based authentication.

/**
 * Renders a Metamask sign-in button
 * @param props - SignInWithMetamaskButton component props
 * @returns Metamask sign-in button JSX element
 */
function SignInWithMetamaskButton(props: SignInWithMetamaskButtonProps): JSX.Element;

interface SignInWithMetamaskButtonProps {
  /** Custom children to render as button content */
  children?: React.ReactNode;
}

Conditional Rendering Components

SignedIn Component

Renders children only when the user is authenticated. Behavior adapts based on router: server component in App Router, client component in Pages Router.

/**
 * Conditional rendering component - shows children when user is signed in
 * @param props - Component props
 * @returns Children if signed in, null otherwise
 */
function SignedIn(props: SignedInProps): JSX.Element | null;

interface SignedInProps {
  /** Content to render when user is signed in */
  children: React.ReactNode;
}

Usage Example:

import { SignedIn, UserButton } from '@clerk/nextjs';

export default function Header() {
  return (
    <header>
      <SignedIn>
        <UserButton />
      </SignedIn>
    </header>
  );
}

SignedOut Component

Renders children only when the user is not authenticated. Behavior adapts based on router: server component in App Router, client component in Pages Router.

/**
 * Conditional rendering component - shows children when user is signed out
 * @param props - Component props
 * @returns Children if signed out, null otherwise
 */
function SignedOut(props: SignedOutProps): JSX.Element | null;

interface SignedOutProps {
  /** Content to render when user is signed out */
  children: React.ReactNode;
}

Usage Example:

import { SignedIn, SignedOut, SignInButton } from '@clerk/nextjs';

export default function Header() {
  return (
    <header>
      <SignedOut>
        <SignInButton />
      </SignedOut>
      <SignedIn>
        <UserButton />
      </SignedIn>
    </header>
  );
}

Protect Component

Renders children only when user meets authentication and authorization requirements. Behavior adapts based on router: server component in App Router, client component in Pages Router.

/**
 * Authorization-based conditional rendering component
 * @param props - Protect component props
 * @returns Children if authorized, fallback or null otherwise
 */
function Protect(props: ProtectProps): JSX.Element | null;

interface ProtectProps {
  /** Content to render when authorized */
  children: React.ReactNode;
  /** Content to render when not authorized */
  fallback?: React.ReactNode;
  /** Custom condition function */
  condition?: (has: (permission: string) => boolean) => boolean;
  /** Required role for authorization */
  role?: string;
  /** Required permission for authorization */
  permission?: string;
}

Usage Example:

import { Protect } from '@clerk/nextjs';

export default function AdminPanel() {
  return (
    <Protect role="admin" fallback={<div>Access denied</div>}>
      <div>Admin panel content</div>
    </Protect>
  );
}

// With custom condition
export default function FeaturePage() {
  return (
    <Protect
      condition={(has) => has('feature:access')}
      fallback={<div>You need feature access</div>}
    >
      <div>Feature content</div>
    </Protect>
  );
}

Control Components

ClerkLoaded Component

Renders children only when Clerk has fully loaded.

/**
 * Renders children when Clerk has loaded
 * @param props - Component props
 * @returns Children when loaded, null otherwise
 */
function ClerkLoaded(props: { children: React.ReactNode }): JSX.Element | null;

ClerkLoading Component

Renders children only while Clerk is loading.

/**
 * Renders children while Clerk is loading
 * @param props - Component props
 * @returns Children while loading, null otherwise
 */
function ClerkLoading(props: { children: React.ReactNode }): JSX.Element | null;

ClerkFailed Component

Renders children when Clerk fails to load.

/**
 * Renders children when Clerk fails to load
 * @param props - Component props
 * @returns Children when failed, null otherwise
 */
function ClerkFailed(props: { children: React.ReactNode }): JSX.Element | null;

ClerkDegraded Component

Renders children when Clerk service is in a degraded state.

/**
 * Renders children when Clerk is in degraded state
 * @param props - Component props
 * @returns Children when degraded, null otherwise
 */
function ClerkDegraded(props: { children: React.ReactNode }): JSX.Element | null;

Redirect Components

RedirectToSignIn Component

Redirects the user to the sign-in page.

/**
 * Redirects user to sign-in page
 * @param props - Redirect props
 * @returns Redirect component
 */
function RedirectToSignIn(props: RedirectToSignInProps): JSX.Element;

interface RedirectToSignInProps {
  /** URL to return to after sign-in */
  redirectUrl?: string;
  /** URL to navigate after successful sign-in */
  afterSignInUrl?: string;
  /** URL to navigate after successful sign-up */
  afterSignUpUrl?: string;
}

RedirectToSignUp Component

Redirects the user to the sign-up page.

/**
 * Redirects user to sign-up page
 * @param props - Redirect props
 * @returns Redirect component
 */
function RedirectToSignUp(props: RedirectToSignUpProps): JSX.Element;

interface RedirectToSignUpProps {
  /** URL to return to after sign-up */
  redirectUrl?: string;
  /** URL to navigate after successful sign-in */
  afterSignInUrl?: string;
  /** URL to navigate after successful sign-up */
  afterSignUpUrl?: string;
}

RedirectToUserProfile Component

Redirects the user to their user profile page.

/**
 * Redirects user to user profile page
 * @param props - Redirect props
 * @returns Redirect component
 */
function RedirectToUserProfile(props?: {}): JSX.Element;

RedirectToOrganizationProfile Component

Redirects the user to the organization profile page.

/**
 * Redirects user to organization profile page
 * @param props - Redirect props
 * @returns Redirect component
 */
function RedirectToOrganizationProfile(props?: {}): JSX.Element;

RedirectToCreateOrganization Component

Redirects the user to the create organization page.

/**
 * Redirects user to create organization page
 * @param props - Redirect props
 * @returns Redirect component
 */
function RedirectToCreateOrganization(props: RedirectToCreateOrganizationProps): JSX.Element;

interface RedirectToCreateOrganizationProps {
  /** URL to navigate after creating organization */
  afterCreateOrganizationUrl?: string;
}

RedirectToTasks Component

Redirects the user to the tasks page.

/**
 * Redirects user to tasks page
 * @param props - Redirect props
 * @returns Redirect component
 */
function RedirectToTasks(props?: {}): JSX.Element;

Additional Components

AuthenticateWithRedirectCallback Component

Handles OAuth/SAML redirect callbacks after authentication.

/**
 * Handles authentication redirect callbacks
 * Used in callback routes to complete OAuth/SAML authentication
 * @param props - Callback props
 * @returns Callback handler component
 */
function AuthenticateWithRedirectCallback(props?: {}): JSX.Element;

GoogleOneTap Component

Renders Google One Tap authentication UI.

/**
 * Renders Google One Tap authentication
 * @param props - GoogleOneTap props
 * @returns Google One Tap component
 */
function GoogleOneTap(props: GoogleOneTapProps): JSX.Element;

interface GoogleOneTapProps {
  /** Customization options for appearance */
  appearance?: Appearance;
}

APIKeys Component

Renders UI for managing API keys.

/**
 * Renders API keys management interface
 * @param props - APIKeys props
 * @returns API keys component
 */
function APIKeys(props?: {}): JSX.Element;

PricingTable Component

Renders Clerk pricing/billing table UI.

/**
 * Renders pricing table component
 * @param props - PricingTable props
 * @returns Pricing table component
 */
function PricingTable(props?: {}): JSX.Element;

Waitlist Component

Renders waitlist management UI.

/**
 * Renders waitlist component
 * @param props - Waitlist props
 * @returns Waitlist component
 */
function Waitlist(props?: {}): JSX.Element;

TaskChooseOrganization Component

Renders organization selection task UI.

/**
 * Renders organization selection task
 * @param props - Task props
 * @returns Task component
 */
function TaskChooseOrganization(props?: {}): JSX.Element;

TaskResetPassword Component

Renders password reset task UI.

/**
 * Renders password reset task
 * @param props - Task props
 * @returns Task component
 */
function TaskResetPassword(props?: {}): JSX.Element;

Common Types

interface Appearance {
  baseTheme?: Theme;
  variables?: Variables;
  elements?: Elements;
  layout?: Layout;
}