Clerk

The Clerk object is the core of the ClerkJS SDK.

Overview

The Clerk object is a singleton which can act as the entry point for gaining access to other Clerk resources, like the active Client, Session and User objects. It also includes helper methods for mounting Clerk Components to your pages.

The Clerk object is always available via window.Clerk.

Attributes

Name	Type	Description
client	Client	The `Client` object for the current window.
session	session \| null \| undefined	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.
user	User \| null \| undefined	A shortcut to `Session.user` which holds the currently active `User object`. If the session is null or undefined, the `user` field will match.
version	string	The ClerkJS SDK version.

Methods

addListener(listener)

addListener(listener: (resources: Resources) => void) => UnsubscribeCallback

Registers a listener that triggers a callback whenever a change in theClient, Session, or User object occurs. This method is primary used to build frontend SDKs like @clerk/clerk-react.

Resources is an interface with the following definition. To import our types, please add @clerk/types:

interface Resources {
  client: ClientResource;
  session?: ActiveSessionResource | null;
  user?: UserResource | null;
}

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, userand sessionwill both be null.
When a session is loading, userand sessionwill be undefined.

Parameters

Name	Type	Description
listener	(resources: Resources) => void	A function to be called when the Client object changes.

Returns

Type	Description
() => void	This method returns a function that can be used to clean up the registered listener.

authenticateWithMetamask(params)

authenticateWithMetamask(params: AuthenticateWithMetamaskParams) => void

Starts an authentication flow that uses the Metamask browser extension to authenticate the user using their public wallet address.

Parameters

Type	Description
AuthenticateWithMetamaskParams	These props allow you to define the URL where the user should be redirected to on successful authentication

Returns

The method has no return value.

buildSignInUrl(opts?: RedirectOptions) => string

Returns the configured url where <SignIn /> is mounted or a custom sign-in page is rendered.

buildSignUpUrl(opts?: RedirectOptions) => string

Returns the configured url where <SignUp /> is mounted or a custom sign-up page is rendered.

buildUserProfileUrl()

buildUserProfileUrl() => string

Returns the url where <UserProfile /> is mounted or a custom user-profile page is rendered.

buildCreateOrganizationUrl()

buildCreateOrganizationUrl() => string

Returns the configured url where <CreateOrganization /> is mounted or a custom create-organization page is rendered.

buildOrganizationProfileUrl()

buildOrganizationProfileUrl() => string

Returns the configured url where <OrganizationProfile /> is mounted or a custom organization-profile page is rendered.

buildUrlWithAuth(to)

buildUrlWithAuth(to: string) => string

Decorates the provided url with the auth token for development instances.

closeSignIn() => void

Closes the <SignIn/> modal.

Parameters

This method accepts no parameters.

Returns

The method has no return value.

closeSignUp() => void

Closes the <SignUp/> modal.

Parameters

This method accepts no parameters.

Returns

The method has no return value.

handleMagicLinkVerification(params)

handleRedirectCallback(params: HandleMagicLinkVerificationParams) => Promise<unknown>

Completes a magic link verification flow once we've reached the magic link results URL.

When users click on magic links they get redirected to the URL that was provided during magic link verification flow initialization. The URL will contain a couple of important query parameters added by Clerk. These are called __clerk_status and __clerk_created_session.

The __clerk_status query parameter is the outcome of the verification and can take three values: verified, failed or expired.

The __clerk_created_session query parameter will hold the ID of the new session, if one was created as a result of the verification. Since the magic link can be opened at any device and not the one that originated the verification, the new session ID might not be available under Client.sessions.

Magic link flows can be completed on the same device that they were initiated or on a completely different browser. For example, a user might start the magic link flow on their desktop browser, but click on the magic link from their mobile phone.

The handleMagicLinkVerification() method takes care of finalizing the magic link flow, depending on the verification outcome.

Upon successful verification, the method will figure out if the sign in or sign up attempt was completed and redirect the user accordingly. As such, it accepts different parameters for the URL it should redirect when sign in/up is completed and the URL which it should redirect when the sign in/up attempt is still pending. Both parameters are optional, but you can provide them to the method up front. The final redirect will depend on the sign in/up attempt's status.

Additionally, the handleMagicLinkVerification() method allows you to execute a callback if the successful verification happened on another device.

In case the magic link verification wasn't successful, the handleMagicLinkVerification() method will throw a MagicLinkError. You can check the error's code property to see if the magic link expired, or the verification simply failed.

Take a look at the function parameters description below for more usage details.

Parameters

Name	Type	Description
params	HandleMagicLinkVerificationParams	These props allow you to define the URLs where the user should be redirected to on successful verification and: completed sign in or sign up attempt. pending sign in or sign up attempt. If the magic link is successfully verified on another device, there's a callback function parameter that allows custom code execution.

Returns

Type	Description
MagicLinkError	MagicLinkError This method will throw a MagicLinkError if the magic link verification failed or the link expired. Check the error's code property for details.

handleRedirectCallback(params)

handleRedirectCallback(params: HandleOAuthCallbackParams) => Promise<void>

Completes a custom OAuth flow started by calling either SignIn.authenticateWithRedirect(params) or SignUp.authenticateWithRedirect(params)

Parameters

Name	Type	Description
params	HandleOAuthCallbackParams	Additional props that define where the user will be redirected to at the end of a successful OAuth flow.

isReady()

isReady() => boolean

Returns true when the ClerkJS library has fully loaded and the Clerk object is ready for use, false otherwise.

Parameters

This method accepts no parameters.

Returns

Type	Description
boolean	This method will return true when the `Clerk` object is ready, false otherwise.

load(options?)

load(options?: ComponentOptions) => Promise<void>

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

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.

Parameters

Name	Type	Description
options	ComponentOptions	Configuration and options for initializing the Clerk object and Clerk Components.

Returns

Type	Description
boolean	This method will return true when the `Clerk` object is ready, false otherwise.

mountSignIn(node: HTMLDivElement, nodeProps?: SignInProps) => void

Renders a <SignIn/> component inside the provided HTML element, allowing to pass any props that configure the component.

Parameters

Name	Type	Description
node	HTMLDivElement	An HTML `<div/>` element which will render the <SignIn/> component.
nodeProps?	SignInProps	Additional props that will be passed to the <SignIn/> component.

Returns

Type	Description
boolean	This method will return true when the `Clerk` object is ready, false otherwise.

mountSignUp(node: HTMLDivElement, nodeProps?: SignUpProps) => void

Renders a <SignUp/> component inside the provided HTML element, allowing to pass any props that configure the component.

Parameters

Name	Type	Description
node	HTMLDivElement	An HTML `<div/>` element which will render the <SignUp/> component.
nodeProps?	SignUpProps	Additional props that will be passed to the <SignUp/> component.

Returns

This method has no return value.

mountUserButton(node, nodeProps?)

mountUserButton(node: HTMLDivElement, nodeProps?: UserButtonProps) => void

Renders a <UserButton/> component for the active user inside the provided HTML element, allowing to pass any props that configure the component.

Parameters

Name	Type	Description
node	HTMLDivElement	An HTML `<div/>` element which will render the <UserButton/> component.
nodeProps?	UserButtonProps	Additional props that will be passed to the <UserButton/> component.

Returns

This method has no return value.

mountUserProfile(node, nodeProps?)

mountUserProfile(node: HtmlDivElement, nodeProps?: UserProfileProps) => void

Renders a <UserProfile/> component for the active user inside the provided HTML element, allowing to pass any props that configure the component.

Parameters

Name	Type	Description
node	HTMLElement	The element that the UserProfile should be mounted in.
nodeProps?	UserProfileProps	Additional props that will be passed to the <UserProfile/> component.

Returns

This method has no return value.

navigate(to)

navigate(to: string) => Promise<unknown>

Helper method which will use the custom push navigation function of your application to navigate to the provided URL or relative path. See the relevant section on routing for more information on navigation.

Parameters

Name	Type	Description
props	SignInProps	Configuration properties that will be passed to the <SignIn/> component.

Returns

This method has no return value.

openSignIn(props: SignInProps) => void

Opens the <SignIn/> component as a modal.

Parameters

Name	Type	Description
props	SignInProps	Configuration properties that will be passed to the <SignIn/> component.

Returns

This method has no return value.

openSignUp(props: SignUpProps) => void

Opens the <SignUp/> component as a modal.

Parameters

Name	Type	Description
props	SignUpProps	Configuration properties that will be passed to the <SignUp/> component.

Returns

This method has no return value.

redirectToCreateOrganization()

redirectToCreateOrganization() => void

Redirects to the configured URL where <CreateOrganization /> is mounted.

redirectToOrganizationProfile()

redirectToOrganizationProfile() => void

Redirects to the configured URL where <OrganizationProfile /> is mounted.

redirectToSignIn(props: RedirectToSignInProps) => Promise<unknown>

Redirects to the sign-in URL, as configured in your Instance settings. This method uses the Clerk.navigate method under the hood.

Parameters

Name	Type	Description
afterSignInUrl	string	Full URL or path to navigate after successful sign-in.
afterSignUpUrl	string	Full URL or path to navigate after successful sign-up. Sets the afterSignUpUrl if the "Sign up" link is clicked.
redirectUrl	string	Full URL or path to navigate after successful sign-in, or sign-up. The same as setting afterSignInUrl and afterSignUpUrl to the same value.

Returns

Type	Description
Promise<unknown>	This method returns a `Promise` which can resolve to any value.

redirectToSignUp(props: RedirectToSignUpProps) => Promise<unknown>

Redirects to the sign-up URL, as configured in your Instance settings. This method uses the Clerk.navigate method under the hood.

Parameters

Name	Type	Description
afterSignInUrl	string	Full URL or path to navigate after successful sign-in.
afterSignUpUrl	string	Full URL or path to navigate after successful sign up. Sets the afterSignUpUrl if the "Sign up" link is clicked.
redirectUrl	string	Full URL or path to navigate after successful sign-in, or sign-up. The same as setting afterSignInUrl and afterSignUpUrl to the same value.

Returns

Type	Description
Promise<unknown>	This method returns a `Promise` which can resolve to any value.

redirectToUserProfile()

redirectToUserProfile() => Promise<unknown>

Redirects to the user profile management URL, as configured in your Instance settings. This method uses the Clerk.navigate method under the hood.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<unknown>	This method returns a `Promise` which can resolve to any value.

redirectWithAuth(to)

redirectWithAuth(to: string) => Promise<unknown>

Redirects to the provided url after decorating it with the auth token for development instances.

setSession(session, beforeEmit?)

setSession(session: SessionResource | string | null, beforeEmit?: (session: SessionResource | null) => any) => Promise<void>

Set the current session on this client to the provided session. The provided session can be either a complete Session object or simply its unique identifier.

Passing null as the session will result in the current session to be removed from the client.

If an active session already exists, it will be replaced with the new one. The change happens in three steps:

The current Session object is set to undefined, which causes the control components to stop rendering their children as though Clerk is still initializing.
The beforeEmit callback is executed. If a Promise is returned, Clerk waits for the Promise to resolve.
The current Session is set to the passed session. This causes the control components to render their children again.

Parameters

Name	Type	Description
session	SessionResource \| string \| null	A `Session` object or `Session ID` string to be set as the current session, or null to simply remove the active session, without setting a new one.
beforeEmit?	(session: SessionResource \| null) => Promise<any> \| void	Callback that will trigger when the current session is set to undefined, before finally being set to the passed session. Usually used for navigation.

Returns

Type	Description
Promise<void>	This method returns a `Promise` which doesn't resolve to any value. The `Promise` will resolve after the passed `session` is set.

signOut(callback?)

signOut(callback?: SignOutCallback) => 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.

Parameters

Name	Type	Description
callback?	SignOutCallback	A callback function that will be called after successful sign out.

Returns

Type	Description
Promise<void>	This method returns a `Promise` which doesn't resolve to any value.

unmountSignIn(node: HTMLDivElement) => void

Unmounts the <SignIn/> component from the specified HTML element.

Parameters

Name	Type	Description
node	HTMLDivElement	The element that the <SignIn/> component will be unmounted from.

Returns

This method has no return value.

unmountSignUp(node: HTMLDivElement) => void

Unmounts the <SignUp/> component from the specified HTML element.

Parameters

Name	Type	Description
node	HTMLDivElement	The element that the <SignUp/> component will be unmounted from.

Returns

This method has no return value.

unmountUserButton(node)

unmountUserButton(node: HTMLDivElement) => void

Unmounts the <UserButton/> component from the specified HTML element.

Parameters

Name	Type	Description
node	HTMLDivElement	The element that the <UserButton/> component will be unmounted from.

Returns

This method has no return value.

unmountUserProfile(node)

unmountUserProfile(node: HTMLDivElement) => void

Unmounts the <UserProfile/> component from the specified HTML element.

Parameters

Name	Type	Description
node	HTMLDivElement	The element that the <UserProfile/> component will be unmounted from.

Returns

This method has no return value.

Interfaces

ComponentOptions

Name	Type	Description
selectInitialSession?	(client: ClientResource) => SessionResource \| undefined	This function can be used to set the initial session in multi-session applications.
navigate?	(to: string) => Promise<unknown> \| unknown	Provide an implementation for the Clerk.navigate method.

AuthenticateWithMetamaskParams

Name	Type	Description
redirectUrl?	string	Full URL or path to navigate after successful sign in or sign up.

HandleMagicLinkVerificationParams

Name	Type	Description
redirectUrl?	string	Full URL or path to navigate after successful magic link verification on the same device, but a sign in or sign up attempt that cannot complete yet. For example, let's say a user has enabled two-factor authentication (2FA). In the sign in flow, the magic link verification may be successfully verified but user needs to complete 2FA before they can log in. Use this parameter to redirect to your 2FA route.
redirectUrlComplete?	string	Full URL or path to navigate after successful magic link verification on the same device and the sign in or sign up attempt has completed. As an example, user tries to sign in via a magic link and they're successfully logged in. Use this parameter to decide where the user will be redirected to.
onVerifiedOnOtherDevice?	Function	Use this callback function to run any custom code on a successful magic link verification on a device different than the one which originated the magic link verification flow. This function provides an opportunity to handle the case where a magic link is opened from another device.

HandleOAuthCallbackParams

Name	Type	Description
afterSignInUrl?	string	Full URL or path to navigate after successful sign in.
afterSignUpUrl?	string	Full URL or path to navigate after successful sign up.
redirectUrl?	Function	Full URL or path to navigate after successful sign in or sign up. The same as setting `afterSignInUrl` and `afterSignUpUrl` to the same value.
secondFactorUrl?	string	Full URL or path to navigate during sign in, if 2FA is enabled.

Name	Type	Description
routing?	RoutingStrategy	The routing strategy for your pages. Supported values are: path: Path based routing. hash(default): Hash based routing. virtual: Virtual based routing.
path?	string	The path where the component is mounted when path-based routing is used. -e.g. /sign-in. This prop is ignored in hash and virtual based routing.
afterSignIn?	string	The full URL or path to navigate after a successful sign in.
signInURL?	string	Full URL or path to the sign up page. Use this property to provide the target of the "Sign In" link that's rendered.

Name	Type	Description
routing?	string	The routing strategy for your pages. Supported values are: path: Path based routing. hash(default): Hash based routing. virtual: Virtual based routing.
path?	string	The path where the component is mounted when path-based routing is used. -e.g. /sign-up. This prop is ignored in hash and virtual based routing.
afterSignIn?	string	The full URL or path to navigate after a successful sign up.
signUpURL?	string	Full URL or path to the sign up page. Use this property to provide the target of the "Sign Up" link that's rendered.

UserButtonProps

Name	Type	Description
afterSignOutAll?	string	Full URL or relative path to navigate after sign out is complete and there are no active sessions on this client.
afterSignOutOne?	string	Full URL or relative path to navigate after sign out is complete.
afterSwitchSession?	string	Full URL or relative path to navigate on the "Add another account" action. This property is used only for multi-session applications.
signInURL?	string	Full URL or relative path to navigate on the "Add another account" action. This property is used only for multi-session applications.
userProfileURL?	string	Full URL or relative path of the user account management interface.

UserProfileProps

Name	Type	Description
routing?	string	The routing strategy for your pages. Supported values are: path: Path based routing. hash(default): Hash based routing. virtual: Virtual based routing.
path?	string	The path where the component is mounted when path-based routing is used. -e.g. /user-profile. This prop is ignored in hash and virtual based routing.
hideNavigation?	boolean	Hides the default navigation bar. Can be used when a custom navigation bar is built.
only?	string	Renders only a specific page of the UserProfile component. Supported values are: account: User account page. security: User security page.

Types

MagicLinkError

Custom error for magic links. Raised when the magic link verification doesn't succeed, either because the link has expired or a general failure. The error's code property will indicate the outcome, its values being:

MagicLinkErrorCode.Expired
MagicLinkErrorCode.Failed

SignOutCallback

() => void | Promise<any>

Name	Description
() => void	A `Function` which doesn't return anything.
Promise<any>	A `Promise` which can resolve to any value.

Clerk

The Clerk object is the core of the ClerkJS SDK.

Attributes

Methods

addListener(listener)

authenticateWithMetamask(params)

buildSignInUrl(opts)

buildSignUpUrl(opts)

buildUserProfileUrl()

buildCreateOrganizationUrl()

buildOrganizationProfileUrl()

buildUrlWithAuth(to)

closeSignIn()

closeSignUp()

handleMagicLinkVerification(params)

handleRedirectCallback(params)

isReady()

load(options?)

mountSignIn(node, nodeProps?)

mountSignUp(node, nodeProps?)

mountUserButton(node, nodeProps?)

mountUserProfile(node, nodeProps?)

navigate(to)

openSignIn(props)

openSignUp(props)

redirectToCreateOrganization()

redirectToOrganizationProfile()

redirectToSignIn(props)

redirectToSignUp(props)

redirectToUserProfile()

redirectWithAuth(to)

setSession(session, beforeEmit?)

signOut(callback?)

unmountSignIn(node)

unmountSignUp(node)

unmountUserButton(node)

unmountUserProfile(node)

Interfaces

ComponentOptions

AuthenticateWithMetamaskParams

HandleMagicLinkVerificationParams

HandleOAuthCallbackParams

SignInProps

SignUpProps

UserButtonProps

UserProfileProps

Types

MagicLinkError

SignOutCallback