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 an important change in the Client object occurs. This method can be used to hook into different steps of the sign in and sign up flow and execute custom logic.

Some things to note for specific changes in the Client object include:

  • 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
Parameters

Name

Description

listener

(resources: Resources) => void

A function to be called when the Client object changes.

Returns

() => void

This method returns a function that can be used to clean up the registered listener.

closeSignIn()

closeSignIn() => void

Closes the <SignIn/> modal.

Parameters
Returns
Parameters

This method accepts no parameters.

Returns

This method has no return value.

closeSignUp()

closeSignUp() => void

Closes the <SignUp/> modal.

Parameters
Returns
Parameters

This method accepts no parameters.

Returns

This method has no return value.

isReady()

isReady() => boolean

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

Parameters
Returns
Parameters

This method accepts no parameters.

Returns

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
Parameters

Name

Description

options

ComponentOptions

Configuration and options for initializing the Clerk object and Clerk Components.

Returns

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
Parameters

Name

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

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
Parameters

Name

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
Returns
Parameters

Name

Description

node

HTMLDivElement

An HTML <div/> element which will render the <UserButton/> component.

options?

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
Returns
Parameters

Name

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: 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
Parameters

Name

Description

to

string

Full URL or relative path to navigate to.

Returns

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
Parameters

Name

Description

props

SignInProps

Configuration properties that will be passed to the <SignIn/> component.

Returns

This method has no return value.

openSignUp(props)

openSignUp(props: SignUpProps) => void

Opens the <SignUp/> component as a modal.

Parameters
Returns
Parameters

Name

Description

props

SignUpProps

Configuration properties that will be passed to the <SignUp/> component.

Returns

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
Parameters

This method accepts no parameters.

Returns

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
Parameters

This method accepts no parameters.

Returns

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
Parameters

This method accepts no parameters.

Returns

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. 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. The beforeEmit callback is executed. If a Promise is returned, Clerk waits for the Promise to resolve.

  3. The current Session is set to the passed session. This causes the control components to render their children again.

Parameters
Returns
Parameters

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.

Returns

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
Parameters

Name

Description

callback?

SignOutCallback

A callback function that will be called after successful sign out.

Returns

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
Parameters

Name

Description

callback?

SignOutCallback

A callback function that will be called after successful sign out.

Returns

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
Parameters

Name

Description

node

HTMLDivElement

The element that the <SignIn/> component will be unmounted from.

Returns

This method has no return value.

unmountSignUp(node)

unmountSignUp(node: HTMLDivElement) => void

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

Parameters
Returns
Parameters

Name

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
Returns
Parameters

Name

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
Returns
Parameters

Name

Description

node

HTMLDivElement

The element that the <UserProfile/> component will be unmounted from.

Returns

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.

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.

afterSignOutAll?

string

Full URL or relative path to navigate after successful sign out, with no other active accounts on the client.

afterSignOutOne?

string

Full URL or relative path to navigate after successful sign out.

Types

SignOutCallback

() => void | Promise<any>

Value

Description

() => void

A Function which doesn't return anyhing.

Promise<any>

A Promise which can resolve to any value.