Get started with React
Learn to install and initialize Clerk in a new Create React App.
Learn more about React authentication with Clerk.
Overview
Clerk is the easiest way to add authentication and user management to your React application. This guide will you walk you through the necessary steps to install and use Clerk in a new create-react-app application. For more in-depth guides, check out our How-to Guides section.
After following this guide, you should have a working React app complete with:
- Fully fledged sign in and sign up flows.
- Google Social Login.
- Secure email/password authentication.
- A prebuilt user profile page.
Looking for a quickstart? We created a demo app to show you how to add Clerk to your project.
Before you start
You need to create a Clerk Application in your Clerk Dashboard. For more information, check out our Set up your application guide.
Creating a new React app
Start by creating a new React application - this is usually done using the create-react-app CLI:
1npx create-react-app
1yarn create react-app
If you wish to use Typescript, just add --typescript
to the commands above. Clerk is written in Typescript, so it works out of the box without any extra configuration. For more information, you can reference the create-react-app documentation.
Installing Clerk
One you have a React app ready, you need to install the Clerk React SDK. This will give you access to our prebuilt Clerk Components and React hooks.
1# Navigate to your application's root directory2# This should be the actual name from3# the previous step4cd my-first-application56# Install the clerk-react package7npm install @clerk/clerk-react
1# Navigate to your application's root directory2# This should be the actual name from3# the previous step4cd my-first-application56# Install the clerk-react package7yarn add @clerk/clerk-react
Now, we need to set the CLERK_FRONTEND_API
environment variable. Go to the API Keys page and copy the Frontend API Key field.
Then, create a file named .env.local
in your application root. Any variables inside this file with the REACT_APP_
prefix will be accessible in your React code via process.env.REACT_APP_VAR_NAME
. Create a REACT_APP_CLERK_FRONTEND_API
variable and set it to the Frontend API
you copied earlier:
# Create the .env.local filetouch .env.local# Add the environment variable. Don't forget to# replace [your-frontend-api] with the actual Frontend API keyecho "REACT_APP_CLERK_FRONTEND_API=[your-frontend-api]" > .env.local
Clerk is now successfully installed! 🎉
To run your app, start the development server and navigate to http://localhost:3000.
1npm start
1yarn start
For more details, consult the Clerk React installation page.
Adding <ClerkProvider />
Clerk requires your application to be wrapped in the <ClerkProvider/>
context. In React, we add this in src/App.jsx
.
Wrap your app with <ClerkProvider/>
and pass the REACT_APP_CLERK_FRONTEND_API
env variable you just created to the frontendApi
prop. Replace your src/App.jsx
with:
import React from "react";import "./App.css";// Import ClerkProviderimport { ClerkProvider } from "@clerk/clerk-react";// Get the Frontend API from the environmentconst frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;function App() {return (// Wrap your entire app with ClerkProvider// Don't forget to pass the frontendApi prop<ClerkProvider frontendApi={frontendApi}><Hello /></ClerkProvider>);}function Hello() {return <div>Hello from Clerk</div>;}export default App;
Navigate to http://localhost:3000 to view the changes. Now, let's add a router.
Adding a router
<ClerkProvider/>
also accepts a navigate
prop that enables Clerk to navigate inside your application without a full page reload, using the same routing logic your app does. Our display components use this prop when navigating between subpages, and when navigating to callback URLs.
You can pass the navigate
prop 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 push function provided by your router. Most React apps use the popular react-router-dom, which is also what we'll be using for this guide. Install it by running the following command:
1npm i react-router-dom
1yarn add react-router-dom
Wrap your <App/>
component with the router by modifying the src/index.jsx
file as shown below:
import React from "react";import ReactDOM from "react-dom";import "./index.css";import App from "./App";import reportWebVitals from "./reportWebVitals";// Import the BrowserRouter from the react-router-dom packageimport { BrowserRouter } from "react-router-dom";ReactDOM.render(<React.StrictMode>{/* Wrap your App component with the Router */}<BrowserRouter><App /></BrowserRouter></React.StrictMode>,document.getElementById("root"));reportWebVitals();
The last step is to give ClerkProvider access to your router, by adding the navigate
prop. In src/App.jsx
import and use the useNavigate
hook, as shown in the example:
import React from "react";import "./App.css";import { ClerkProvider } from "@clerk/clerk-react";// import the useNavigate hookimport { useNavigate } from "react-router-dom";const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;function App() {const navigate = useNavigate();return (// Pass the push method to the navigate prop<ClerkProvider frontendApi={frontendApi} navigate={(to) => navigate(to)}><Hello /></ClerkProvider>);}function Hello() {return <div>Hello from Clerk</div>;}export default App;
The navigate
function must return the result of the push
function.
Your app is now configured 🎉 Next, let's see how you can use Clerk to require authentication before navigating to a protected page.
Requiring authentication
The easiest way to require authentication before showing a protected page, is to use our Control Components:
- ​
<SignedIn/>
: Renders its children only when a user is signed in. - ​
<SignedOut/>
: Renders its children only when there's no active user. - ​
<RedirectToSignIn/>
: Triggers a redirect to the sign in page.
The following example shows you how to compose our flexible Control Components to build auth flows that match your needs. Please note that you don't need to use any additional APIs, everything shown below is just Javascript.
import React from "react";import "./App.css";import {ClerkProvider,SignedIn,SignedOut,UserButton,useUser,RedirectToSignIn,} from "@clerk/clerk-react";import { useNavigate } from "react-router-dom";const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;function App() {const navigate = useNavigate();// If the current route is listed as public, render it directly// Otherwise, use Clerk to require authenticationreturn (<ClerkProvider frontendApi={frontendApi} navigate={(to) => navigate(to)}><SignedIn><Hello /></SignedIn><SignedOut><RedirectToSignIn /></SignedOut></ClerkProvider>);}function Hello() {return <div>Hello from Clerk</div>;}
Visit http://localhost:3000 to see your page - you'll immediately get redirected to the Clerk Hosted Sign In page:

Hello, world!
That's all you need to start using Clerk. Now you can say hello to your user!
Let's edit the <Hello/>
component. We're going to use the useUser
hook and the UserButton
component as shown in the example:
import React from "react";import "./App.css";import {ClerkProvider,SignedIn,SignedOut,UserButton,useUser,RedirectToSignIn,} from "@clerk/clerk-react";import { useNavigate } from "react-router-dom";const frontendApi = process.env.REACT_APP_CLERK_FRONTEND_API;function App() {const navigate = useNavigate();return (<ClerkProvider frontendApi={frontendApi} navigate={(to) => navigate(to)}><SignedIn><Hello /></SignedIn><SignedOut><RedirectToSignIn /></SignedOut></ClerkProvider>);}function Hello() {// Get the user's first nameconst { user } = useUser();return (<div className="App-header">{/* Mount the UserButton component */}<UserButton />{user ? <h1>Hello, {user.firstName}!</h1> : null}</div>);}export default App;
Visit https://localhost:3000 again to see your page. If you haven't signed in yet, you will be redirected to the sign in page. Sign in using your preferred method and the home page will become accessible:

And that's all!
By default, you app will use the Clerk Hosted Pages to display the sign in and sign up flows. Check the documentation of the <SignIn/> and <SignUp/> components to learn how you can mount them directly in your app.
Next steps
You now have a working React + Clerk app. Going forwards, you can:
- Learn how to deploy your app to production.
- Check out our in-depth guides for the most usual use cases in the How-to Guides section.
- Learn more about the Clerk Components and the Clerk Hosted Pages.
- Come say hi in our Discord channel 👋