Descope Components

Descope Components are components used to render Descope Flows and provide context in your application. This includes the UI elements and logic as defined in your project console.

Before using the Descope Components, make sure to import and initialize the relevant SDK.

Auth Provider

The AuthProvider is the main component that wraps your application and provides the necessary context for the Descope SDK to work.

Base URL Configuration

Here is an example of configuring the AuthProvider with a custom domain:

// Using custom domain for baseUrl
<AuthProvider
  projectId="your-project-id"
  baseUrl="https://auth.yourcompany.com"
  baseStaticUrl="https://auth.yourcompany.com/pages"
>
  <App />
</AuthProvider>

baseUrl

The baseUrl is the URL (your custom domain, if configured) where all backend/flow requests will go to from your client application. This includes authentication requests, flow interactions, and API calls to Descope services.

When using a custom domain for Descope, you should set this to your custom domain URL instead of the default Descope URLs.

baseStaticUrl

The baseStaticUrl is specifically for the URL where the SDK will fetch static assets for flow rendering, such as CSS files, images, and other static resources. This is typically your custom domain + "/pages" (e.g., https://auth.yourcompany.com/pages).

baseCdnUrl

The baseCdnUrl is the URL of the custom CDN that you can use to host your static assets. This is used if you do not wish to use descopecdn.com as the default CDN.

Important

Both the baseUrl and baseStaticUrl are recommended to be set when using a custom domain, or if you're on a Private Cloud Deployment of Descope.

You can choose to store the session token in a cookie instead of localStorage. This is done by passing the sessionTokenViaCookie prop to the AuthProvider component.

The Descope SDK will then automatically store the session token on the DS cookie.

Note

Use this option if session token will stay small (less than 1k). Session token can grow, especially in cases of using authorization, or adding custom claims.

Here are the available cookie configuration options, in the AuthProvider component:

OptionTypeDescriptionDefault
sameSiteStrict,Lax,NoneControls the cookie's same-site policy.Strict
securebooleanSpecifies whether the cookie is sent over secure (HTTPS) connections.true

Here is an example of setting both sameSite and secure explicitly:

<AuthProvider
  projectId="your-project-id"
  sessionTokenViaCookie={{ sameSite: 'None', secure: true }}
  baseUrl="https://auth.app.example.com"
  baseStaticUrl="https://auth.app.example.com/pages"
>
  <App />
</AuthProvider>

Example Configuration of AuthProvider (for each SDK)

import { AuthProvider } from '@descope/react-sdk';
 
const AppRoot = () => {
	return (
        <AuthProvider
            projectId="my-project-id"
            sessionTokenViaCookie
            baseUrl = "https://auth.app.example.com"
            baseStaticUrl="https://auth.app.example.com/pages"
        >
		<App />
		</AuthProvider>
	);
};

Now, whenever you call fetch(), the cookie will automatically be sent with the request. Descope backend SDKs also support extracting the token from the DS cookie.

Note

The session token cookie, by default, is set as a Secure cookie and therefore will only be sent over HTTPS connections.

In addition, some browsers (e.g. Safari) may not store Secure cookie if the hosted page is running on an HTTP protocol.

Descope Flow Component

Customize the Descope Flow Component by passing in the following props:

  • theme: theme can be "light", "dark" or "os", which auto selects a theme based on the OS theme. Default is "light"
  • styleId: style Id can be the id of the style you wish to run your flows with
  • debug: debug can be set to true to enable debug mode
  • redirectUrl: Redirect URL for OAuth and SSO (will be used when redirecting back from the OAuth provider / IdP), or for "Magic Link" and "Enchanted Link" (will be used as a link in the message sent to the the user)
  • redirectAfterSuccess: Redirect URL after the flow's success.
  • redirectAfterError: Redirect URL upon error in the flow.
  • autoFocus: autoFocus can be true, false or "skipFirstScreen". Default is true.
    • true: automatically focus on the first input of each screen
    • false: do not automatically focus on screen's inputs
    • "skipFirstScreen": automatically focus on the first input of each screen, except first screen
  • errorTransformer: errorTransformer is a function that receives an error object and returns a string. The returned string will be displayed to the user. For more information, refer to Customizing Flow Errors.
  • locale: locale can be any supported locale which the flow's screen translated to. if not provided, the locale is taken from the browser's locale.
  • logger: logger is an object describing how to log info, warn and errors.
  • dismissScreenErrorOnInput: when used, the general error message that appears on screen on user input will be cleared once the form is being re-edited. The value should be set to true.

Note

For information on parameters that can be utilized within your flow (e.g. tenant, screen inputs, etc.), refer to the Flow Inputs Doc.

import { Descope } from '@descope/react-sdk'
 
const App = () => {
    return (
        <Descope
            flowId="my-flow-id"
            // theme="dark"
            // styleId=<Style ID>
            // debug={true}
            // redirectUrl=<redirectUrl>
            // redirectAfterSuccess="/"
            // redirectAfterError="/error-page"
            // autoFocus="skipFirstScreen"
            // errorTransformer={errorTransformer}
        />
    )
}

Triggered Events

  • onReady: onReady is an event that is triggered when the flow is ready to be displayed. It's useful for showing a loading indication before the page is ready.
  • onSuccess: Function that executes when authentication succeeds. User information is returned and accessible with e.detail.user.
  • onError: Function that executes with authentication fails.
import { Descope } from '@descope/react-sdk'
 
const App = () => {
    return (
        <Descope
            flowId="my-flow-id"
            onReady={() => {
              console.log('Flow is ready');
            }}
            onSuccess={(e) => console.log(e.detail.user)}
            onError={(e) => console.log('Could not log in!')}
        />
    )
}

Default Flows

Use default flow components that render the Descope component with a predefined flow ID.

import { SignInFlow } from '@descope/react-sdk'
// you can choose flow to run from the following
import { SignUpFlow } from '@descope/react-sdk'
import { SignUpOrInFlow } from '@descope/react-sdk'
 
const App = () => {
    return (
        <SignInFlow
            onSuccess={(e) => console.log('Logged in!')}
            onError={(e) => console.log('Could not logged in!')}
        />
    )
}

Widgets

Widgets are Descope components that let you delegate operations to your customers. Whether your implementation is tenant-based or not, you can embed these components inside your application to allow your customers to perform various self-service operations.

Customize the widgets by passing in the following props. These customizations can be applied to any of the available widgets:

  • theme: theme can be "light", "dark" or "os", which auto selects a theme based on the OS theme. Default is "light"
  • widgetId: widgetId is the ID of the widget you wish to use.
  • onLogout: onLogout is an event that is triggered when the user logs out. It's useful for redirecting the user to the login page.
  • onReady: onReady is an event that is triggered when the widget is ready to be displayed. It's useful for showing a loading indication before the page is ready.
import { UserProfile } from '@descope/react-sdk';
 
<UserProfile
	widgetId="user-profile-widget"
	theme={theme} // light / dark / os (auto detect)
    onReady={() => {
      console.log('Widget is ready');
    }}
    onLogout={() => {
      // add your own logout callback here
      window.location.href = '/login';
    }}
/>

You can learn more about Widgets and their implementation on the Widgets Overview doc.

Was this helpful?

On this page