Installation

Learn how to make Clerk React components available in your project.

Overview

If you are using Next.js, please make sure to install @clerk/nextjs as @clerk/clerk-react is incompatible

Clerk React is a wrapper around ClerkJS. It is the recommended way to integrate Clerk into your React application.

Clerk React provides React.js implementations of Clerk Components; highly customizable, pre-built components that you can use to build beautiful user management applications. You can find display components for building sign in, sign up, account switching and user profile management pages as well as flow control components that act as helpers for implementing a seamless authentication experience.

Clerk React comes loaded with custom hooks. These hooks give you access to the Clerk object, and a set of useful helper methods for signing in and signing up.

This doc assumes that you already have a basic working knowledge of React and that you have already set up a React project. If you're new to React, you can check our Getting Started guides on React or Next.js.

Setting up Clerk React

You need to create a Clerk Application in your Clerk Dashboard before you can set up Clerk React. For more information, check out our Set up your application guide.

There's an ES module for Clerk React, available under the @clerk/clerk-react npm package. Use npm or yarn to install the Clerk React module.

1
# Install the package with npm.
2
npm install @clerk/clerk-react
3

4
# Alternative install method with yarn.
5
yarn add @clerk/clerk-react

Set Environment Keys

Below is an example of your .env.local file. To get the respective keys, go to the API Keys page in the Clerk dashboard.

.env1

It is also possible to pass these keys into the Clerk components and functions manually.

Clerk provider

The ClerkProvider allows you to render Clerk Components and access the available Clerk React hooks in any nested component. You'll have to wrap your application once with a <ClerkProvider/>.

Render a <ClerkProvider/> component at the root of your React app so that it is available everywhere you need it.

In order to use<ClerkProvider/>, first you need to locate the entry point file of your React app. Usually this is your src/index.js (Create React App) or pages/_app (Next.js) file. In general, you're looking for the file where the ReactDOM.render function gets called.

1
import ReactDOM from "react-dom";
2
import { ClerkProvider } from "@clerk/clerk-react";
3

4
// App is the top-level component. Wrap your whole
5
// DOM tree with a ClerkProvider. Pass the Frontend 
6
// API host as a prop.
7
const clerk_pub_key = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY;
8
function App() {
9
  return (
10
    <ClerkProvider publishableKey={clerk_pub_key}>
11
      {/* Your application tree goes here. */}
12
    </ClerkProvider>
13
  );
14
}
15

16
// Assuming the React app will render inside an 
17
// HTMLElement with id "app".
18
const appEl = document.getElementById("app");
19
ReactDOM.render(<App />, appEl);

Routing

A common scenario when using React is to navigate through your application without a full page reload. Our display components use this prop when navigating between subpages and when navigating to callback URLs.

The <ClerkProvider/> navigate prop allows you to provide a function which takes the destination URL as an argument and performs a "push" navigation. You should not implement the push yourself, but instead wrap the navigate function provided by your router.

You can find examples of setting up path-based routing for React Router and Next.js.

1
import { BrowserRouter as Router, useNavigate } from "react-router-dom";
2
import { ClerkProvider } from "@clerk/clerk-react";
3

4
// App is the top-level component. Place the Router 
5
// above ClerkProvider and provide the React Router 
6
// navigate function to ClerkProvider.
7
const clerk_pub_key = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY;
8
function App() {
9
  const navigate = useNavigate();
10

11
  return (
12
    <Router>
13
      <ClerkProvider
14
        publishableKey={clerk_pub_key}
15
        navigate={(to) => navigate(to)}
16
      >
17
        {/* Your application tree goes here. */}
18
      </ClerkProvider>
19
    </Router>
20
  );
21
}