Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerkstage.dev

Use Clerk with React

Learn how to use Clerk to quickly and easily add secure authentication and user management to your React application.

Install @clerk/clerk-react

Once you have a React application ready, you need to install Clerk's React SDK. This gives you access to our prebuilt components and hooks for React applications.

terminal
npm install @clerk/clerk-react
terminal
yarn add @clerk/clerk-react
terminal
pnpm add @clerk/clerk-react

Set environment keys

Below is an example of an .env file. If you are signed into your Clerk Dashboard, your keys should become visible by clicking on the eye icon.

.env
REACT_APP_CLERK_PUBLISHABLE_KEY={{pub_key}}

Configure <ClerkProvider />

Clerk requires your React application to be wrapped in the <ClerkProvider /> component. The <ClerkProvider /> component provides active session and user context to Clerk's hooks and other components.

app.tsx
import React from "react";
import "./App.css";
import { ClerkProvider } from "@clerk/clerk-react";
 
if (!process.env.REACT_APP_CLERK_PUBLISHABLE_KEY) {
  throw new Error("Missing Publishable Key")
}
const clerkPubKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY;
 
function App() {
  return (
    <ClerkProvider publishableKey={clerkPubKey}>
      <div>Hello from clerk</div>
    </ClerkProvider>
  );
}
 
export default App;

Protecting your pages

Clerk offers Control Components that allow you to protect your pages. These components are used to control the visibility of your pages based on the user's authentication state.

app.tsx
import React from "react";
import "./App.css";
import {
  ClerkProvider,
  SignedIn,
  SignedOut,
  UserButton,
  useUser,
  RedirectToSignIn,
} from "@clerk/clerk-react";
 
if (!process.env.REACT_APP_CLERK_PUBLISHABLE_KEY) {
  throw "Missing Publishable Key"
}
 
const clerkPubKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY;
 
function App() {
  return (
    <ClerkProvider publishableKey={clerkPubKey}>
      <SignedIn>
        <Welcome />
      </SignedIn>
      <SignedOut>
        <RedirectToSignIn />
      </SignedOut>
    </ClerkProvider>
  );
}
 
function Welcome() {
  return <div>Hello you are signed in</div>;
}
 
export default App;

At this point, your application is fully protected by Clerk and uses Clerk's Account Portal pages that are available out of box. Start your React application via npm run start, visit http://localhost:3000, and sign up to get access to your application.

Using a routing library with Clerk

Clerk can work with any routing library. Below is an example of how to use Clerk with React Router and how to embed the Clerk components in your application.

app.tsx
import {
  ClerkProvider,
  SignedIn,
  SignedOut,
  RedirectToSignIn,
  SignIn,
  SignUp,
  UserButton,
} from "@clerk/clerk-react";
import { BrowserRouter, Route, Routes, useNavigate } from "react-router-dom";
 
if (!process.env.REACT_APP_CLERK_PUBLISHABLE_KEY) {
  throw new Error("Missing Publishable Key")
}
 
const clerkPubKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY;
 
function PublicPage() {
  return (
    <>
      <h1>Public page</h1>
      <a href="/protected">Go to protected page</a>
    </>
  );
}
 
function ProtectedPage() {
  return (
    <>
      <h1>Protected page</h1>
      <UserButton />
    </>
  );
}
 
function ClerkProviderWithRoutes() {
  const navigate = useNavigate();
 
  return (
    <ClerkProvider
      publishableKey={clerkPubKey}
      navigate={(to) => navigate(to)}
    >
      <Routes>
        <Route path="/" element={<PublicPage />} />
        <Route
          path="/sign-in/*"
          element={<SignIn routing="path" path="/sign-in" />}
        />
        <Route
          path="/sign-up/*"
          element={<SignUp routing="path" path="/sign-up" />}
        />
        <Route
          path="/protected"
          element={
          <>
            <SignedIn>
              <ProtectedPage />
            </SignedIn>
            <SignedOut>
              <RedirectToSignIn />
            </SignedOut>
          </>
          }
        />
      </Routes>
    </ClerkProvider>
  );
}
 
function App() {
  return (
    <BrowserRouter>
      <ClerkProviderWithRoutes />
    </BrowserRouter>
  );
}
 
export default App;

Read session and user data

Clerk provides a set of hooks and helpers that you can use to access the active session and user data in your React application. Here are examples of how to use these helpers.

useAuth

The useAuth hook is a convenient way to access the current auth state. This hook provides the minimal information needed for data-loading and helper methods to manage the current active session.

pages/example.tsx
import { useAuth } from "@clerk/clerk-react";
 
export default function Example() {
  const { isLoaded, userId, sessionId, getToken } = useAuth();
 
  // In case the user signs out while on the page.
  if (!isLoaded || !userId) {
    return null;
  }
 
  return (
    <div>
      Hello, {userId} your current active session is {sessionId}
    </div>
  );
}

useUser

The useUser hook is a convenient way to access the current user data where you need it. This hook provides the user data and helper methods to manage the current active session.

pages/example.tsx
import { useUser } from "@clerk/clerk-react";
 
export default function Example() {
  const { isLoaded, isSignedIn, user } = useUser();
 
  if (!isLoaded || !isSignedIn) {
    return null;
  }
 
  return <div>Hello, {user.firstName} welcome to Clerk</div>;
}

Next steps

Now that you have an application integrated with Clerk, you will want to read the following documentation:

Customization & Localization

Learn how to customize and localize the Clerk components.

Learn More

Authentication Components

Learn more about all our authentication components.

Learn More

Client Side Helpers

Learn more about our client side helpers and how to use them.

Learn More

What did you think of this content?

Clerk © 2023