Clerk context

The Clerk context is used to retrieve the Clerk object. This is most commonly used to build alternatives to our display components.

If you only want information about the active user, we recommend using the User context instead.

The Clerk object

The Clerk object contains the following properties:

client

Client

This object contains a list of Sessions tied to the client, and utilities to Sign In or Sign Up to create an additional Session.

user

User | null | undefined

This field is a shortcut to session.user. Ifsession is null or undefined, this field will match.

session

Session | null | undefined

This field contains 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.

closeSignIn

() => void;

Closes the SignIn modal.

closeSignUp

() => void;

Closes the SignUp modal.

openSignIn

() => void;

Opens the SignIn display component as a modal.

openSignUp

() => void;

Opens the SignUp display component as a modal.

setSession

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

Changes session to the passed Session, Session ID, or null.

The change happens in three steps:

  1. session is updated to undefined - the same state that is used while Clerk is loading. This causes the control components to stop rendering their children.
  2. beforeEmit is run. If a promise is returned, Clerk waits for the promise to resolve.
  3. session is updated to the new value. This causes the control components to render their children again.

useClerk (Hook)

Use the useClerk hook to retrieve the Clerk object from any function component.

import { useClerk } from "@clerk/clerk-react";
const SignInButton = () => {
const clerk = useClerk();
return <button onClick={() => clerk.openSignIn({})}>Sign in</button>;
};

WithClerk (Function-as-child)

Use the function-as-child pattern with WithClerk to retrieve the Clerk object within a class component.

import { WithClerk } from "@clerk/clerk-react";
class SignInButton extends React.Component {
render() {
return (
<WithClerk>
{(clerk) => (
<button onClick={() => clerk.openSignIn({})}>Sign in</button>
)}
</WithClerk>
);
}
}

withClerk (Higher-order component)

Use the withClerk higher-order component to pass the Clerk object as a prop to any component.

import { withClerk } from "@clerk/clerk-react";
class SignInButton extends React.Component {
render() {
return (
<button onClick={() => this.props.clerk.openSignIn({})}>Sign in</button>
);
}
}
const SignInButtonWithClerk = withClerk(SignInButton);

WithClerkProp Typescript utility

In Typescript, use with WithClerkProp utility type to make the compiler aware of the clerk prop.

import { withClerk, WithClerkProp } from "@clerk/clerk-react";
class SignInButton extends React.Component<WithClerkProp<{}>> {
render() {
return (
<button onClick={() => this.props.clerk.openSignUp({})}>Sign ins</button>
);
}
}
const SignInButtonWithClerk = withClerk(SignInButton);