Installation
Learn how to make Clerk React components available in your project.
Overview
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.
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.
# Install the package with npm.npm install @clerk/clerk-react# Alternative install method with yarn.yarn add @clerk/clerk-react
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.
Replace the frontendApi
prop with the Frontend API host found on the API Keys page.
1import ReactDOM from "react-dom";2import { ClerkProvider } from "@clerk/clerk-react";34// App is the top-level component. Wrap your whole5// DOM tree with a ClerkProvider. Pass the Frontend6// API host as a prop.7function App() {8return (9<ClerkProvider frontendApi="clerk.[your-domain].com">10{/* Your application tree goes here. */}11</ClerkProvider>12);13}1415// Assuming the React app will render inside an16// HTMLElement with id "app".17const appEl = document.getElementById("app");18ReactDOM.render(<App />, appEl);
1import { ClerkProvider } from '@clerk/nextjs';23// App is the top-level component. Wrap your whole4// DOM tree with a ClerkProvider. Pass the Frontend5// API host as a prop.6function App({ Component, pageProps }) {7return (8<ClerkProvider frontendApi="clerk.[your-domain].com">9<Component {...pageProps} />10</ClerkProvider>11);12}
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.
1import { BrowserRouter as Router, useNavigate } from "react-router-dom";2import { ClerkProvider } from "@clerk/clerk-react";34// App is the top-level component. Place the Router5// above ClerkProvider and provide the React Router6// navigate function to ClerkProvider.7function App() {8const navigate = useNavigate();910return (11<Router>12<ClerkProvider13frontendApi="clerk.[your-domain].com"14navigate={(to) => navigate(to)}15>16{/* Your application tree goes here. */}17</ClerkProvider>18</Router>19);20}
1import { useRouter } from "next/router";2import { ClerkProvider } from "@clerk/nextjs";34function App({ Component, pageProps }) {5const { push } = useRouter();67return (8<ClerkProvider9frontendApi="clerk.[your-domain].com"10navigate={(to) => push(to)}11>12<Component {...pageProps} />13</ClerkProvider>14);15}