Clerk

The Clerk object is a singleton for mounting components, and accessing the active Client, Session and User objects.

Usage

The Clerk object is always available in window.Clerk, but if you're using React we highly recommend using the useClerk() hook instead.

Attributes

Name

Description

client

Client

The Client object for the current window.

user

User | null | undefined

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

session

Session | null | undefined

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

Common functions

openSignIn

Arguments
Return
Arguments

Name

Description

options?

SignInOptions

afterSignIn?: Where to navigate after sign in is complete

signUpURL?: The route where "Sign up instead" links. If not passed, Sign up will open as a modal.

Return

No return value.

Opens the SignIn modal.

closeSignIn

Arguments
Return
Arguments

No arguments.

Return

No return value.

Closes the SignIn modal.

openSignUp

Arguments
Return
Arguments

Name

Description

options?

SignUpOptions

afterSignUp?: Where to navigate after sign in is complete

signInURL?: The route where "Sign in instead" links. If not passed, Sign in will open as a modal.

Return

No return value.

Opens the SignUp modal.

closeSignUp

Arguments
Return
Arguments

No arguments.

Return

No return value.

Closes the SignUp modal.

setSession

Arguments
Return
Arguments

Name

Description

session

Session | string | null

A Session object or Session ID string to be set as this.session, or null to remove the active session.

beforeEmit?

(session: Session | null) => Promise<any> | void

Usually used for navigation — the passed function will run while this.session is set to undefined, before finally being set to the passed session.

Return

Returns a promise that resolves after after passed session is set. The promise does not resolve a value.

Change this.session to the passed session. The change happens in three steps:

  1. this.session is set to undefined, which causes the control components to stop rendering their children as though Clerk is still initializing.

  2. beforeEmit is run. If a promise is returned, Clerk waits for the promise to resolve.

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

Advanced functions

Usually, these functions are only needed when creating a plugin for a framework (like clerk-react), or when integrating Clerk into a vanilla Javascript application.

If you're using React, we recommend using components instead of these functions. For example, the useClerk hook is an alternative to addListener, and the SignUp component is an alternative to mountSignUp and unmountSignUp.

addListener

Arguments
Return
Arguments

Name

Description

listener

(emission: ListenerEmission) => void

Pass in a function to be called when the Client object changes. ListenerEmission has the form:

client: Client

session: Session | null | undefined

user: User | null | undefined

Return

No return value.

Add a listener to be called whenever the Client object changes, including during different steps of the Sign in and Sign up process.

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

mountSignIn

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the SignIn flow should be mounted in.

options?

SignInOptions

routing?: How to route subpages, "hash" (default) or "path"

path?: Required for path-based routing, the root path where the component is mounted (e.g. /sign-in)

afterSignIn?: Where to navigate after sign in is complete

signUpURL?: The route where "Sign up instead" links

Return

No return value.

Mounts a SignIn flow in the given element.

unmountSignIn

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the SignIn flow should be unmounted from.

Return

No return value.

Unmounts a SignIn flow from the given element.

mountSignUp

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the SignUp flow should be mounted in.

options?

SignUpOptions

routing?: How to route subpages, "hash" (default) or "path"

path?: Required for path-based routing, the root path where the component is mounted (e.g. /sign-up)

afterSignUp?: Where to navigate after sign up is complete

signInURL?: The route where "Sign in instead" links

Return

No return value.

Mounts a SignUp flow in the given element.

unmountSignUp

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the SignUp flow should be unmounted from.

Return

No return value.

Unmounts a SignUp flow from the given element.

mountUserProfile

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the UserProfile should be mounted in.

options?

UserProfileOptions

routing?: How to route subpages, "hash" (default) or "path"

path?: Required for path-based routing, the root path where the component is mounted (e.g. /user)

Return

No return value.

Mounts the UserProfile of the active user in the given element.

unmountUserProfile

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the UserProfile should be unmounted from.

Return

No return value.

Unmounts the UserProfile of the active user from the given element.

mountUserButton

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the UserButton should be mounted in.

options?

UserButtonOptions

afterSignOutAll?: Where to navigate after sign out is complete, and no other user is signed in on the client

afterSignOutOne?: Multi-session mode only. Where to navigate after sign out is complete, but a different user is still signed in on the client

afterSwitchSession?: Multi-session mode only. Where to navigate after switching which session is active

userProfileURL?: The route where "Manage account" links

signInURL?: Multi-session mode only. The route where "Add another account" links

Return

No return value.

Mounts the UserButton of the active user in the given element.

unmountUserButton

Arguments
Return
Arguments

Name

Description

element

HTMLElement

The element that the UserButton flow should be unmounted from.

Return

No return value.

Unmounts the UserButton of the active user from the given element.