Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

Clerk

This 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

NameTypeDescription
versionstringA getter for the Clerk SDK version
loadedbooleanA getter to see if the Clerk object is ready for use or not
isSatellitebooleanClerk Flag for satellite apps
domainstringA getter for the current Clerk app's domain.
Prefixed with clerk. on production if not already prefixed.
Returns "" when ran on the server
proxyUrlstringA 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).
instanceId'production' | 'development'A getter to see the if a Clerk instance is running in production or development mode
clientClientThe Client object for the current window.
sessionSession | null | undefinedThe 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.
userUser | null | undefinedA shortcut to Session.user which holds the currently active User object. If the session is null or undefined, the user field will match.
organizationOrganization | null | undefinedA 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.
publishableKeystring | undefinedThe publishable key from your Clerk Dashboard, used to connect to Clerk

Methods

constructor()

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

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.

Properties

NameTypeDescription
keystringThe publishable key from your Clerk Dashboard, used to connect to Clerk
options?DomainOrProxyUrl | undefinedThe domain or proxy URL used to connect to Clerk

DomainOrProxyUrl

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

NameTypeDescription
proxyUrl?never | string | ((url: URL) => string)The proxyUrl used to connect to Clerk. If a function, will be called with a URL made from window.location.href
domain?never | string | ((url: URL) => string)The domain used to connect to Clerk. If a function, will be called with a URL made from window.location.href

isReady()

function isReady(): boolean;

Indicates when the ClerkJS library has fully loaded and the Clerk object is ready for use.

Returns

TypeDescription
booleanReturns true when the Clerk object is ready. Returns false otherwise.

load()

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

Initializes the Clerk object and loads all necessary environment configuration and instance settings from the Frontend API(opens in a new tab).

It is absolutely necessary to call this method before using the Clerk object in your code. Refer to the ClerkJS installation guide for more details.

ClerkOptions

All props below are optional.

NameTypeDescription
appearanceAppearance | undefinedOptional object to style your components. Will only affect Clerk Components and not Account Portal pages.
localizationLocalization | undefinedOptional object to localize your components. Will only affect Clerk Components and not Account Portal pages.
navigate((to: string) => Promise<unknown> | unknown) | undefinedA function which takes the destination path as an argument and performs a "push" navigation.
pollingboolean | undefinedDictates if we should poll against Clerk's backend every 5 minutes. Defaults to true
selectInitialSession((client: Client) => Session | null) | undefinedAn 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.
standardBrowserboolean | undefinedControls if ClerkJS will load with the standard browser set up using Clerk cookies. Defaults to true
supportEmailstring | undefinedOptional support email for display in authentication screens
touchSessionboolean | undefinedIndicates whether the session should be "touched" when user interactions occur, used to record these interactions. Defaults to true
signInUrlstring | undefinedThe default URL to use to direct to when the user signs in.
signUpUrlstring | undefinedThe default URL to use to direct to when the user signs up.
afterSignInUrlstring | undefinedThe default URL to use after the user signs in.
afterSignUpUrlstring | undefinedThe default URL to use after the user signs up.
allowedRedirectOriginsArray<string | RegExp> | undefinedOptional array of domains used to validate against the query param of an auth redirect.
If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning passed to the console.
isInterstitialboolean | undefinedIndicates that Clerk.js will be loaded from interstitial. Defaults to false
isSatelliteboolean | ((url: URL) => boolean) | undefinedClerk Flag for satellite apps. Experimental.

signOut()

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

Signs out the active user from all sessions in a multi-session application, or simply the current session in a single-session context. The current client will be deleted. You can also specify a specific session to sign out by passing the sessionId parameter.

SignOutOptions

NameTypeDescription
sessionId?string | undefinedSpecify a specific session to sign out. Useful for multi-session applications.

addListener()

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

Registers a listener that triggers a callback whenever a change in the Client, Session, or User object occurs. This method is primary used to build frontend SDKs like @clerk/clerk-react(opens in a new tab).

Resources

NameType
clientClient
sessionSession | null | undefined
userUser | null | undefined
organizationOrganization | null | undefined
lastOrganizationInvitationOrganizationInvitation | null | undefined
lastOrganizationMemberOrganizationMembership | null | undefined

Please note that the Session and User object have a special relationship that the type definition alone does not capture:

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

Returns

type UnsubscribeCallback = () => void;

The addListener method returns an UnsubscribeCallback function that can be used to remove the listener from the Clerk object.

authenticateWithMetamask()

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

AuthenticateWithMetamaskParams

NameTypeDescription
redirectUrl?string | undefinedFull URL or path to navigate after successful sign in or sign up.
signUpContinueUrl?string | undefinedThe location to continue navigation to in the sign up process if data is missing.
customNavigate?((to: string) => Promise<unknown> | unknown) | undefinedAllows you to define a custom navigation function

Components

Sign In

Sign In logo

Read docs

Sign Up

Sign Up logo

Read docs

User Profile

User Profile logo

Read docs

User Button

User Button logo

Read docs

Organization Profile

Organization Profile logo

Read docs

Organization Switcher

Organization Switcher logo

Read docs

Create Organization

Create Organization logo

Read docs

Additional methods

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

Organization

Redirect

Build URLs

Handle navigation

Session

Last updated on January 31, 2024

What did you think of this content?

Clerk © 2024