Search…
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
Description
client
Client
The Client object for the current window.
environment
Environment
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:
1
interface Resources {
2
client: ClientResource;
3
session?: ActiveSessionResource | null;
4
user?: UserResource | null;
5
}
Copied!
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.
Parameters
Returns
Name
Description
listener
(resources: Resources) => void
A function to be called when the Client object changes.
() => 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
Returns
Name
Description
These props allow you to define the URL where the user should be redirected to on successful authentication
This method has no return value.

closeSignIn()

closeSignIn() => void
Closes the <SignIn/> modal.
Parameters
Returns
This method accepts no parameters.
This method has no return value.

closeSignUp()

closeSignUp() => void
Closes the <SignUp/> modal.
Parameters
Returns
This method accepts no parameters.
This 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
Throws
Name
Description
params
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.
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
Description
params?
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
Returns
This method accepts no parameters.
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
Returns
Name
Description
options
Configuration and options for initializing the Clerk object and Clerk Components.
Promise<void>
This method returns a Promise which doesn't resolve to any value.

mountSignIn(node, nodeProps?)

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
Returns
Name
Description
node
HTMLDivElement
An HTML <div/> element which will render the <SignIn/> component.
nodeProps?
Additional props that will be passed to the <SignIn/> component.
This method has no return value.

mountSignUp(node, nodeProps?)

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
Returns
Name
Description
node
HTMLDivElement
An HTML <div/> element which will render the <SignUp/> component.
nodeProps?
Additional props that will be passed to the <SignUp/> component.
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
Returns
Name
Description
node
HTMLDivElement
An HTML <div/> element which will render the <UserButton/> component.
options?
Additional props that will be passed to the <UserButton/> component.
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
Returns
Name
Description
node
HTMLElement
The element that the UserProfile should be mounted in.
nodeProps?
Additional props that will be passed to the <UserProfile/> component.
This method has no return value.
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
Returns
Name
Description
to
string
Full URL or relative path to navigate to.
Promise<unknown>
This method returns a Promise that can resolve with any value.

openSignIn(props)

openSignIn(props: SignInProps) => void
Opens the <SignIn/>component as a modal.
Parameters
Returns
Name
Description
props
Configuration properties that will be passed to the <SignIn/> component.
This method has no return value.

openSignUp(props)

openSignUp(props: SignUpProps) => void
Opens the <SignUp/> component as a modal.
Parameters
Returns
Name
Description
props
Configuration properties that will be passed to the <SignUp/> component.
This method has no return value.

redirectToSignIn()

redirectToSignIn() => 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
Returns
This method accepts no parameters.
Promise<unknown>
This method returns a Promise which can resolve to any value.

redirectToSignUp()

redirectToSignUp() => 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
Returns
This method accepts no parameters.
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
Returns
This method accepts no parameters.
Promise<unknown>
This method returns a Promise which can resolve to any value.

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:
  1. 1.
    The current Session object is set to undefined, which causes the control components to stop rendering their children as though Clerk is still initializing.
  2. 2.
    The beforeEmit callback is executed. If a Promise is returned, Clerk waits for the Promise to resolve.
  3. 3.
    The current Session is set to the passed session. This causes the control components to render their children again.
Parameters
Returns
Name
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.
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
Returns
Name
Description
callback?
A callback function that will be called after successful sign out.
Promise<void>
This method returns a Promise which does not resolve to any value.

signOutOne(callback?)

signOutOne(callback?: SignOutCallback) => Promise<void>
Signs out the active user from the current session. For a multi-session application this means that the rest of the session for the current client will remain, but the user will not be authenticated.
Parameters
Returns
Name
Description
callback?
A callback function that will be called after successful sign out.
Promise<void>
This method returns a Promise which does not resolve to any value.

unmountSignIn(node)

unmountSignIn(node: HTMLDivElement) => void
Unmounts the <SignIn/> component from the specified HTML element.
Parameters
Returns
Name
Description
node
HTMLDivElement
The element that the <SignIn/> component will be unmounted from.
This method has no return value.

unmountSignUp(node)

unmountSignUp(node: HTMLDivElement) => void
Unmounts the <SignUp/> component from the specified HTML element.
Parameters
Returns
Name
Description
node
HTMLDivElement
The element that the <SignUp/> component will be unmounted from.
This method has no return value.

unmountUserButton(node)

unmountUserButton(node: HTMLDivElement) => void
Unmounts the <UserButton/> component from the specified HTML element.
Parameters
Returns
Name
Description
node
HTMLDivElement
The element that the <UserButton/> component will be unmounted from.
This method has no return value.

unmountUserProfile(node)

unmountUserProfile(node: HTMLDivElement) => void
Unmounts the <UserProfile/> component from the specified HTML element.
Parameters
Returns
Name
Description
node
HTMLDivElement
The element that the <UserProfile/> component will be unmounted from.
This method has no return value.

Interfaces

ComponentOptions

Property
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

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

HandleMagicLinkVerificationParams

Name
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
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?
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.
secondFactorUrl?
string
Full URL or path to navigate during sign in, if 2FA is enabled.

SignInProps

Property
Description
routing?
string
The routing strategy for your pages. Supported values are:
  • path: Path based routing.
  • hash: Hash based routing.
  • virtual: Virtual based routing.
path?
string
The root URL where the component is mounted on.
afterSignIn?
string
The full URL or path to navigate after a successful sign in.
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.

SignUpProps

Property
Description
routing?
string
The routing strategy for your pages. Supported values are:
  • path: Path based routing.
  • hash: Hash based routing.
  • virtual: Virtual based routing.
path?
string
The root URL where the component is mounted on.
afterSignUp?
string
The full URL or path to navigate after a successful sign up.
signInURL?
string
Full URL or path to the sign in page. Use this property to provide the target of the "Sign In" link that's rendered.

UserButtonProps

Property
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 after a successful account change. 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

Property
Description
routing?
string
The routing strategy for your pages. Supported values are:
  • path: Path based routing.
  • hash: Hash based routing.
  • virtual: Virtual based routing.
path?
string
The root URL where the component is mounted on.
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>
Value
Description
() => void
A Function which doesn't return anyhing.
Promise<any>
A Promise which can resolve to any value.
Last modified 6d ago