Docs

<ClerkProvider>

The <ClerkProvider> component is required to integrate Clerk into your React application, providing session and user context to Clerk's hooks and components.

The recommended approach is to wrap your entire app with <ClerkProvider> at the entry point to make authentication globally accessible. If you only need authentication for specific routes or pieces of your application, render <ClerkProvider> deeper in the component tree. This allows you to implement Clerk's functionality precisely where required without impacting the rest of your app.

Usage

app/layout.tsx
import React from 'react'
import { ClerkProvider } from '@clerk/nextjs'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  )
}
_app.tsx
import { ClerkProvider } from '@clerk/nextjs'
import type { AppProps } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ClerkProvider {...pageProps}>
      <Component {...pageProps} />
    </ClerkProvider>
  )
}

export default MyApp
index.tsx
import React from 'react'
import ReactDOM from 'react-dom'
import { ClerkProvider } from '@clerk/clerk-react'
import App from './App'

const publishableKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY

ReactDOM.render(
  <React.StrictMode>
    <ClerkProvider publishableKey={publishableKey}>
      <App />
    </ClerkProvider>
  </React.StrictMode>,
  document.getElementById('root'),
)

Note

Other meta-frameworks, like Remix, have wrappers around <ClerkProvider> to make their integrations tighter.

Properties

  • Name
    afterMultiSessionSingleSignOutUrl
    Type
    string
    Description

    The full URL or path to navigate to after a signing out from a currently active account in a multi-session app.

  • Name
    afterSignOutUrl
    Type
    string
    Description

    The full URL or path to navigate to after a successful sign-out.

  • Name
    allowedRedirectOrigins?
    Type
    Array<string | RegExp>
    Description

    An optional array of domains to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.

  • Name
    allowedRedirectProtocols?
    Type
    Array<string>
    Description

    An optional array of protocols to validate user-provided redirect URLs against. If no match is made, the redirect is considered unsafe and the default redirect will be used with a warning logged in the console.

  • Name
    appearance?
    Type
    Appearance | undefined
    Description

    Optional object to style your components. Will only affect Clerk components and not Account Portal pages.

  • Name
    clerkJSUrl?
    Type
    string
    Description

    Define the URL that @clerk/clerk-react should hot-load @clerk/clerk-js from.

  • Name
    clerkJSVariant?
    Type
    string
    Description

    If your web application only uses Control components, you can set this value to headless and load a minimal ClerkJS bundle for optimal page performance.

  • Name
    clerkJSVersion?
    Type
    string
    Description

    Define the npm version for @clerk/clerk-js.

  • Name
    domain?
    Type
    string | ((url: URL) => boolean)
    Description

    This option sets the domain of the satellite application. If your application is a satellite application, this option is required.

  • Name
    isSatellite?
    Type
    boolean | ((url: URL) => boolean)
    Description

    This option defines that the application is a satellite application.

  • Name
    localization
    Type
    Localization | undefined
    Description

    Optional object to localize your components. Will only affect Clerk components and not Account Portal pages.

  • Name
    publishableKey
    Type
    string
    Description

    The Clerk Publishable Key for your instance. This can be found on the API keys page in the Clerk Dashboard.

  • Name
    routerPush?
    Type
    (to: string) => Promise<unknown> | void
    Description

    A function which takes the destination path as an argument and performs a "push" navigation.

  • Name
    routerReplace?
    Type
    (to: string) => Promise<unknown> | void
    Description

    A function which takes the destination path as an argument and performs a "replace" navigation.

  • Name
    signInFallbackRedirectUrl?
    Type
    string
    Description

    The fallback URL to redirect to after the user signs in, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.

  • Name
    signUpFallbackRedirectUrl?
    Type
    string
    Description

    The fallback URL to redirect to after the user signs up, if there's no redirect_url in the path already. Defaults to /. It's recommended to use the environment variable instead.

  • Name
    signInForceRedirectUrl?
    Type
    string
    Description

    If provided, this URL will always be redirected to after the user signs in. It's recommended to use the environment variable instead.

  • Name
    signUpForceRedirectUrl?
    Type
    string
    Description

    If provided, this URL will always be redirected to after the user signs up. It's recommended to use the environment variable instead.

  • Name
    signInUrl
    Type
    string
    Description

    This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances. It is required to be set for a satellite application in a development instance. It's recommended to use the environment variable instead.

  • Name
    signUpUrl
    Type
    string
    Description

    This URL will be used for any redirects that might happen and needs to point to your primary application on the client-side. This option is optional for production instances but must be set for a satellite application in a development instance. It's recommended to use the environment variable instead.

  • Name
    supportEmail?
    Type
    string
    Description

    Optional support email for display in authentication screens. Will only affect Clerk components and not Account Portal pages.

  • Name
    telemetry?
    Type
    false | { disabled?: boolean; debug?: boolean } | undefined
    Description

    Controls whether or not Clerk will collect telemetry data.

  • Name
    syncHost
    Type
    string
    Description

    Chrome Extension only To enable, pass the URL of the web application that the extension will sync the authentication state from. See the dedicated guide for more information.

  • Name
    nonce?
    Type
    string
    Description

    This nonce value will be passed to the @clerk/clerk-js script tag. Use it to implement a strict-dynamic CSP. Requires the dynamic prop to also be set.

  • Name
    sdkMetadata?
    Type
    { name: string; version: string; environment?: string }
    Description

    Contains information about the SDK that the host application is using. You don't need to set this value yourself unless you're developing an SDK.

  • Name
    standardBrowser?
    Type
    boolean
    Description

    By default, ClerkJS is loaded with the assumption that cookies can be set (browser setup). On native platforms this value must be set to false. You don't need to set this value yourself unless you're developing an SDK.

  • Name
    selectInitialSession?
    Type
    (client: ClientResource) => ActiveSessionResource | null
    Description

    By default, the last active session is used during client initialization. This option allows you to override that behavior, e.g. by selecting a specific session. You don't need to set this value yourself unless you're developing an SDK.

  • Name
    touchSession?
    Type
    boolean
    Description

    By default, the Clerk Frontend API touch endpoint is called during page focus to keep the last active session alive. This option allows you to disable this behavior. You don't need to set this value yourself unless you're developing an SDK.

  • Name
    initialState?
    Type
    InitialState
    Description

    Provide an initial state of the Clerk client during server-side rendering. You don't need to set this value yourself unless you're developing an SDK.

  • Name
    dynamic?
    Type
    boolean
    Description

    (For Next.js only) Indicates whether or not Clerk should make dynamic auth data available based on the current request. Defaults to false. Opts the application into dynamic rendering when true. For more information, see Next.js rendering modes and Clerk.

  • Name
    waitlistUrl?
    Type
    string
    Description

    Full URL or path to the waitlist page. If undefined, will redirect to the Account Portal waitlist page.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on