Docs

Clerk class

The Clerk class is the main entrypoint class for the @clerk/clerk-js package. It contains a number of methods and properties for interacting with the Clerk API.

Properties

  • Name
    version
    Type
    string
    Description

    A getter for the Clerk SDK version

  • Name
    loaded
    Type
    boolean
    Description

    A getter to see if the Clerk object is ready for use or not

  • Name
    isSatellite
    Type
    boolean
    Description

    Clerk Flag for satellite apps

  • Name
    domain
    Type
    string
    Description

    A getter for the current Clerk app's domain.
    Prefixed with clerk. on production if not already prefixed.
    Returns "" when ran on the server

  • Name
    proxyUrl
    Type
    string
    Description

    A getter for your Clerk app's proxy URL. Required for applications that run behind a reverse proxy.
    Can be either a relative path (/__clerk) or a full URL (https://<your-domain>/__clerk).

  • Name
    instanceType
    Type
    'production' | 'development'
    Description

    A getter to see if a Clerk instance is running in production or development mode

  • Name
    client
    Type
    Client
    Description

    The Client object for the current window.

  • Name
    session
    Type
    Session | null | undefined
    Description

    The currently active Session, which is guaranteed to be one of the sessions in Client.sessions. If there is no active session, this field will be null. If the session is loading, this field will be undefined.

  • Name
    user
    Type
    User | null | undefined
    Description

    A shortcut to Session.user which holds the currently active User object. If the session is null or undefined, the user field will match.

  • Name
    organization
    Type
    Organization | null | undefined
    Description

    A shortcut to the last active Session.user.organizationMemberships which holds an instance of a Organization object. If the session is null or undefined, the user field will match.

  • Name
    publishableKey
    Type
    string | undefined
    Description

    The Clerk Publishable Key for your instance. This can be found on the API keys page in the Clerk Dashboard.

Methods

addListener()

Registers a listener that triggers a callback whenever a change in the Client, Session, or User object occurs. This method is primarily used to build frontend SDKs like @clerk/clerk-react. Returns an UnsubscribeCallback function that can be used to remove the listener from the Clerk object.

function addListener(listener: (emission: Resources) => void): UnsubscribeCallback

Resources

Note

Note the following about User and Session:

  • When there is an active session, user === session.user.
  • When there is no active session, User and Session will both be null.

authenticateWithMetamask()

function authenticateWithMetamask({
  redirectUrl,
  signUpContinueUrl,
  customNavigate,
}?: AuthenticateWithMetamaskParams): Promise<void>

AuthenticateWithMetamaskParams

  • Name
    redirectUrl?
    Type
    string | undefined
    Description

    The full URL or path to navigate to after a successful sign in or sign up.

  • Name
    signUpContinueUrl?
    Type
    string | undefined
    Description

    The URL to navigate to in the sign-up process if data is missing.

  • Name
    customNavigate?
    Type
    ((to: string) => Promise<unknown> | unknown) | undefined
    Description

    A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

authenticateWithCoinbaseWallet()

function authenticateWithCoinbaseWallet({
  redirectUrl,
  signUpContinueUrl,
  customNavigate,
}?: AuthenticateWithCoinbaseWalletParams): Promise<void>

AuthenticateWithCoinbaseWalletParams

  • Name
    redirectUrl?
    Type
    string | undefined
    Description

    The full URL or path to navigate to after a successful sign in or sign up.

  • Name
    signUpContinueUrl?
    Type
    string | undefined
    Description

    The full URL or path to navigate to in the sign-up process if data is missing.

  • Name
    customNavigate?
    Type
    ((to: string) => Promise<unknown> | unknown) | undefined
    Description

    A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

authenticateWithOKXWallet()

Starts a sign-in flow that uses the OKX Wallet to authenticate the user using their Web3 wallet address.

function authenticateWithOKXWallet(props?: AuthenticateWithOKXWalletParams): Promise<void>

AuthenticateWithOKXWalletParams

  • Name
    redirectUrl?
    Type
    string | undefined
    Description

    The full URL or path to navigate to after a successful sign-in or sign-up.

  • Name
    signUpContinueUrl?
    Type
    string | undefined
    Description

    The full URL or path to navigate to in the sign-up process if data is missing.

  • Name
    customNavigate?
    Type
    ((to: string) => Promise<unknown> | unknown) | undefined
    Description

    A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    The user has agreed to the legal compliance documents.

authenticateWithWeb3()

function authenticateWithWeb3({
  redirectUrl,
  signUpContinueUrl,
  customNavigate,
  strategy,
}: ClerkAuthenticateWithWeb3Params): Promise<void>

ClerkAuthenticateWithWeb3Params

  • Name
    redirectUrl?
    Type
    string | undefined
    Description

    The full URL or path to navigate to after a successful sign in or sign up.

  • Name
    signUpContinueUrl?
    Type
    string | undefined
    Description

    The full URL or path to navigate to in the sign-up process if data is missing.

  • Name
    customNavigate?
    Type
    ((to: string) => Promise<unknown> | unknown) | undefined
    Description

    A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows.

  • Name
    strategy
    Type
    Web3Strategy
    Description

    The Web3 verification strategy.

constructor()

Create an instance of the Clerk class with dedicated options.

This method is only available when importing Clerk from @clerk/clerk-js, rather than using a Window script.

class Clerk {
  constructor(key: string, options?: DomainOrProxyUrl)
}

Parameters

  • Name
    key
    Type
    string
    Description

    The Clerk Publishable Key for your instance. This can be found on the API keys page in the Clerk Dashboard.

  • Name
    options?
    Type
    DomainOrProxyUrl | undefined
    Description

    The domain or proxy URL used to connect to Clerk.

DomainOrProxyUrl

Only one of the two properties are allowed to be set at a time.

  • Name
    proxyUrl?
    Type
    never | string | ((url: URL) => string)
    Description

    The proxy URL used to connect to Clerk. If a function, will be called with a URL made from window.location.href.

  • Name
    domain?
    Type
    never | string | ((url: URL) => string)
    Description

    The domain used to connect to Clerk. If a function, will be called with a URL made from window.location.href.

load()

Initializes the Clerk object and loads all necessary environment configuration and instance settings from the Frontend API.

You must call this method before using the Clerk object in your code. Refer to the quickstart guide for more information.

function load(options?: ClerkOptions): Promise<void>

ClerkOptions

All props below are optional.

  • Name
    appearance
    Type
    Appearance | undefined
    Description

    Optional object to style your components. Will only affect Clerk components and not Account Portal pages.

  • Name
    localization
    Type
    Localization | undefined
    Description

    Optional object to localize your components. Will only affect Clerk components and not Account Portal pages.

  • Name
    routerPush?
    Type
    (to: string) => Promise<unknown> | void
    Description

    A function which takes the destination path as an argument and performs a "push" navigation.

  • Name
    routerReplace?
    Type
    (to: string) => Promise<unknown> | void
    Description

    A function which takes the destination path as an argument and performs a "replace" navigation.

  • Name
    polling
    Type
    boolean | undefined
    Description

    Dictates if we should poll against Clerk's backend every 5 minutes. Defaults to true.

  • Name
    selectInitialSession
    Type
    ((client: Client) => Session | null) | undefined
    Description

    An optional function which allows you to control which active session is the initial session to base a user's state off of. Defaults to the first session in the client's sessions array.

  • Name
    standardBrowser
    Type
    boolean | undefined
    Description

    Controls if ClerkJS will load with the standard browser set up using Clerk cookies. Defaults to true.

  • Name
    supportEmail
    Type
    string | undefined
    Description

    Optional support email for display in authentication screens.

  • Name
    touchSession
    Type
    boolean | undefined
    Description

    Indicates whether the session should be "touched" when user interactions occur, used to record these interactions. Defaults to true.

  • Name
    signInUrl
    Type
    string | undefined
    Description

    The default URL to use to direct to when the user signs in. It's recommended to use the environment variable instead.

  • Name
    signUpUrl
    Type
    string | undefined
    Description

    The default URL to use to direct to when the user signs up. It's recommended to use the environment variable instead.

  • Name
    signInForceRedirectUrl?
    Type
    string
    Description

    If provided, this URL will always be redirected to after the user signs in. It's recommended to use the environment variable instead.

  • Name
    signUpForceRedirectUrl?
    Type
    string
    Description

    If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.

  • Name
    signInFallbackRedirectUrl?
    Type
    string
    Description

    The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.

  • Name
    signUpFallbackRedirectUrl?
    Type
    string
    Description

    The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.

  • Name
    afterSignOutUrl?
    Type
    string
    Description

    The full URL or path to navigate to after a successful sign-out.

  • Name
    allowedRedirectOrigins?
    Type
    Array<string | RegExp>
    Description

    An optional array of domains to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.

  • Name
    allowedRedirectProtocols?
    Type
    Array<string>
    Description

    An optional array of protocols to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.

  • Name
    isSatellite
    Type
    boolean | ((url: URL) => boolean) | undefined
    Description

    Clerk flag for satellite apps. Experimental.

  • Name
    telemetry?
    Type
    false | { disabled?: boolean; debug?: boolean } | undefined
    Description

    Controls whether or not Clerk will collect telemetry data.

signOut()

  • In a multi-session application: Signs out the active user from all sessions
  • In a single-session context: Signs out the active user from the current session

The current client will be deleted. You can specify a specific session to sign out by passing the sessionId parameter.

function signOut(options?: SignOutOptions): Promise<void>
// OR
function signOut(
  signOutCallback?: () => void | Promise<any>,
  options?: SignOutOptions,
): Promise<void>

SignOutOptions

  • Name
    sessionId?
    Type
    string
    Description

    Specify a specific session to sign out. Useful for multi-session applications.

  • Name
    redirectUrl?
    Type
    string
    Description

    The full URL or path to navigate to after sign out is complete.

Components

The Clerk class also contains a number of methods for interacting with prebuilt components.

<SignIn />

<SignUp />

<GoogleOneTap />

<UserButton />

<UserProfile />

<OrganizationProfile />

<OrganizationSwitcher />

<CreateOrganization />

<OrganizationList />

<Waitlist />

Additional methods

In addition to the methods listed above, the Clerk class also has the following methods:

Organization

Waitlist

Redirect

Build URLs

Handle navigation

Session

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on