useClerk

Access the Clerk object inside your components.

Overview

The useClerk hook accesses the Clerk object. It can be used to retrieve any object in the ClerkJS SDK. Moreover, it allows access to all of the Clerk object's methods, giving you the freedom to build alternatives to any Clerk Component.

This API is intended to be used for advanced use cases (eg: building a completely custom oauth flow) or as an escape hatch giving access to lower-level APIs.

There are a couple of alternative methods to retrieve the Clerk object if you cannot use hooks.

Usage

Make sure you've followed the installation guide for Clerk React before running the snippets below.

An example of the useClerk hook in action is shown below. We get access to the Clerk object in order to render a button that opens the sign in form as a modal. Note that if your component is not a descendant of the <ClerkProvider/> component, the useClerk hook will throw an error.

1
import { useClerk } from "@clerk/clerk-react";
2

3
function SignInButton() {
4
  const clerk = useClerk();
5
  
6
  return (
7
    <button onClick={() => clerk.openSignIn({})}>
8
      Sign in
9
    </button>
10
  );
11
}

Alternatives

Make sure you've followed the installation guide for Clerk React before running the snippets below.There are times where using a hook might be inconvenient. For such cases, there are alternative ways to get access to the Clerk object.

Clerk provides the <WithClerk/> component and the withClerk higher order component directive that will allow your wrapped components to get access to the Clerk object.

withClerk

The withClerk function offers a Higher Order Component (HOC) that you can wrap your own components with, and they will have access to the Clerk object.

The Clerk object will be accessible in the wrapped component under the clerk prop.

1
import { withClerk } from "@clerk/clerk-react";
2

3
class SignInButton extends React.Component {
4
  render() {
5
    return (
6
      <button onClick={() => this.props.clerk.openSignIn({})}>
7
        Sign in
8
      </button>
9
    );
10
  }
11
}
12

13
// Wrap your component with the useClerk HOC.
14
export const SignInButtonWithClerk = withClerk(SignInButton);

<WithClerk />

If you really want to stretch JSX capabilities and you cannot use the withClerk higher order component, we provide a <WithClerk/> component that accepts a Function as a child. Inside this function, the Clerk object will be accessible.

1
import { WithClerk } from "@clerk/clerk-react";
2

3
class SignInButton extends React.Component {
4
  render() {
5
    return (
6
      <WithClerk>
7
        {(clerk) => (
8
          <button onClick={() => clerk.openSignIn({})}>
9
            Sign in
10
          </button>
11
        )}
12
      </WithClerk>
13
    );
14
  }
15
}

Typescript support

If you're using Typescript, Clerk provides a WithClerkProp type to make the compiler aware of the clerk prop for your components.

You can use the WithClerkProp type in combination with both the withClerk higher order component and the <WithClerk/> component.

The example below uses the withClerk higher order component.

1
import { withClerk, WithClerkProp } from "@clerk/clerk-react";
2

3
class SignInButton extends React.Component<WithClerkProp<{}>> {
4
  render() {
5
    return (
6
      <button onClick={() => this.props.clerk.openSignUp({})}>
7
        Sign in
8
      </button>
9
    );
10
  }
11
}
12

13
export const SignInButtonWithClerk = withClerk(SignInButton);