Added loading spinner for Flows that take time to load

.env.example

@@ -3,6 +3,9 @@ DESCOPE_TENANT_ID= # Your Descope Tenant ID
 DESCOPE_FLOW_ID="sign-up-or-in" # Your Descope flow ID
 DESCOPE_STYLE_ID= # Your Descope Style ID
 DESCOPE_FLOW_DEBUG= # Set to true in case you want to debug your flow
+DESCOPE_BG= # Optional page background color or https:// image URL
+DESCOPE_FLOW_LOADING= # Set to true to show a loading spinner while the flow initializes
+DESCOPE_LOADING_COLOR= # Optional loading spinner color (defaults to bg color, then #0082b5)
 REACT_APP_DESCOPE_BASE_URL= # Descope API base URL
 REACT_APP_USE_ORIGIN_BASE_URL= # Set in case you want to use the origin as
 REACT_APP_FAVICON_URL= # Set in case you want to use a custom favicon

README.md

@@ -55,20 +55,25 @@ These are the different query parameters you can use:
 5. `bg` query parameter is optional. If you wish to use a different background color or URL, you can use this parameter.
    - **Color name**: You can use a [web color](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value), e.g. `bg=red`, `bg=%23ff0000`. Note that some symbols such as `#` will have to be URL encoded.
    - **Image URL**: You can specify a URL to an image such as `https://example.com/background.png`. This image will be sized to cover the screen.
+   - When `bg` is a color, the flow loading spinner uses the same color by default.
 
-6. `wide` query parameter is optional. If wide mode is nedded use `wide=true`. This will widen the flow component that is rendered, which is used for large forms made with Flow screens.
+6. `loading` query parameter is optional. By default, no loading spinner is shown. Set `loading=true` to show a spinner while the flow initializes and during redirect steps (for example, when the first step is SSO).
 
-7. `theme` query parameter is optional. The default value is `light`, but otherwise it will override the theme for your flows rendered with the SDK.
+7. `loading_color` query parameter is optional. Sets the loading spinner color using the same formats as `bg` (including bare hex, e.g. `loading_color=ffffff`). Only applies when `loading=true`. If omitted, the spinner uses `bg` when it is a color; otherwise it defaults to `#0082b5`.
 
-8. `style` query parameter is optional. The default style in your project will be used if not defined, but this allows you to override the `style` for the flows rendered with the SDK.
+8. `wide` query parameter is optional. If wide mode is nedded use `wide=true`. This will widen the flow component that is rendered, which is used for large forms made with Flow screens.
 
-9. `store_last_auth_user` query parameter is optional. Pass this parameter to ensure the last authenticated user is not saved when the flow ends. For example, append `store_last_auth_user=false` to the URL to disable saving the last user.
+9. `theme` query parameter is optional. The default value is `light`, but otherwise it will override the theme for your flows rendered with the SDK.
 
-10. Additional query parameters prefixed with `client.` are passed to the `Descope` component as its `client` prop. For example: `client.k1=v1&client.k2=v2` becomes `{ k1: 'v1', k2: 'v2' }`.
+10. `style` query parameter is optional. The default style in your project will be used if not defined, but this allows you to override the `style` for the flows rendered with the SDK.
 
-11. `width` & `height` are optional query parameters, controlling the sizing of the flow screen in either pixels or a percentage of the viewport (e.g. `50%`, `1200px`). Any value larger than the screen is clamped down.
+11. `store_last_auth_user` query parameter is optional. Pass this parameter to ensure the last authenticated user is not saved when the flow ends. For example, append `store_last_auth_user=false` to the URL to disable saving the last user.
 
-12. `title` query parameter is optional. If provided, it sets the browser tab/document title (e.g. `title=Sign%20in`).
+12. Additional query parameters prefixed with `client.` are passed to the `Descope` component as its `client` prop. For example: `client.k1=v1&client.k2=v2` becomes `{ k1: 'v1', k2: 'v2' }`.
+
+13. `width` & `height` are optional query parameters, controlling the sizing of the flow screen in either pixels or a percentage of the viewport (e.g. `50%`, `1200px`). Any value larger than the screen is clamped down.
+
+14. `title` query parameter is optional. If provided, it sets the browser tab/document title (e.g. `title=Sign%20in`).
 
 **Using .env**
 

src/App.css

@@ -87,6 +87,33 @@ body,
 	display: inline-block;
 }
 
+.flow-loading-overlay {
+	position: fixed;
+	inset: 0;
+	z-index: 1000;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	background: rgba(255, 255, 255, 0.88);
+	backdrop-filter: blur(2px);
+}
+
+.flow-loading-spinner {
+	width: 44px;
+	height: 44px;
+	border-radius: 50%;
+	border: 3px solid
+		color-mix(in srgb, var(--flow-loading-color, #0082b5) 20%, transparent);
+	border-top-color: var(--flow-loading-color, #0082b5);
+	animation: flow-loading-spin 0.8s linear infinite;
+}
+
+@keyframes flow-loading-spin {
+	to {
+		transform: rotate(360deg);
+	}
+}
+
 h1 {
 	margin: 0px;
 	font-weight: 800;

src/App.test.tsx

@@ -18,8 +18,16 @@ const mockAuthProvider = jest.fn();
 
 jest.mock('@descope/react-sdk', () => ({
 	...jest.requireActual('@descope/react-sdk'),
-	Descope: ({ onSuccess, ...props }: { onSuccess: () => void }) => {
+	Descope: ({
+		onSuccess,
+		onReady = () => {},
+		...props
+	}: {
+		onSuccess: () => void;
+		onReady: () => void;
+	}) => {
 		mockDescope(props);
+		setTimeout(onReady, 0);
 		return (
 			<button data-testid="descope-button" type="button" onClick={onSuccess}>
 				Descope
@@ -173,6 +181,48 @@ describe('App component', () => {
 		);
 	});
 
+	test('shows a loading overlay until the flow is ready when loading=true', async () => {
+		window.location.pathname = `/${packageJson.homepage}/${validProjectId}`;
+		window.location.search = `?flow=${flowId}&loading=true`;
+		render(<App />);
+		expect(screen.getByTestId('flow-loading-overlay')).toBeInTheDocument();
+		await waitFor(() =>
+			expect(
+				screen.queryByTestId('flow-loading-overlay')
+			).not.toBeInTheDocument()
+		);
+	});
+
+	test('hides the loading overlay by default', async () => {
+		window.location.pathname = `/${packageJson.homepage}/${validProjectId}`;
+		window.location.search = `?flow=${flowId}`;
+		render(<App />);
+		await waitFor(() =>
+			expect(mockDescope).toHaveBeenCalledWith(
+				expect.objectContaining({ flowId })
+			)
+		);
+		expect(
+			screen.queryByTestId('flow-loading-overlay')
+		).not.toBeInTheDocument();
+	});
+
+	test('uses loading_color for the spinner when provided', async () => {
+		window.location.pathname = `/${packageJson.homepage}/${validProjectId}`;
+		window.location.search = `?flow=${flowId}&loading=true&loading_color=ff0000`;
+		render(<App />);
+		const spinner = await screen.findByTestId('flow-loading-spinner');
+		expect(spinner).toHaveStyle({ '--flow-loading-color': '#ff0000' });
+	});
+
+	test('uses bg color for the spinner when loading_color is not provided', async () => {
+		window.location.pathname = `/${packageJson.homepage}/${validProjectId}`;
+		window.location.search = `?flow=${flowId}&loading=true&bg=00ff00`;
+		render(<App />);
+		const spinner = await screen.findByTestId('flow-loading-spinner');
+		expect(spinner).toHaveStyle({ '--flow-loading-color': '#00ff00' });
+	});
+
 	test('that send_session_token search param enables sendSessionToken', async () => {
 		window.location.pathname = `/${packageJson.homepage}/${validProjectId}`;
 		window.location.search = `?flow=${flowId}&send_session_token=true`;

src/App.tsx

@@ -1,11 +1,18 @@
 import { AuthProvider, Descope } from '@descope/react-sdk';
 import { FlowJWTResponse } from '@descope/web-component';
 import clsx from 'clsx';
-import React, { useEffect, useMemo, useCallback, CSSProperties } from 'react';
+import React, {
+	useEffect,
+	useMemo,
+	useCallback,
+	useState,
+	CSSProperties
+} from 'react';
 import './App.css';
 import Done from './components/Done';
 import Welcome from './components/Welcome';
 import FlowGate from './components/FlowGate';
+import FlowLoadingOverlay from './components/FlowLoadingOverlay';
 import useOidcMfa from './hooks/useOidcMfa';
 import { env } from './env';
 import { logger } from './utils/logger';
@@ -25,6 +32,29 @@ const normalizeBackgroundParam = (
 	return value;
 };
 
+const DEFAULT_LOADING_COLOR = '#0082b5';
+
+const isBackgroundImageUrl = (value: string | undefined) =>
+	Boolean(value?.startsWith('https://'));
+
+const getLoadingSpinnerColor = ({
+	loadingColor,
+	background
+}: {
+	loadingColor: string | undefined;
+	background: string | undefined;
+}) => {
+	if (loadingColor && !isBackgroundImageUrl(loadingColor)) {
+		return loadingColor;
+	}
+
+	if (background && !isBackgroundImageUrl(background)) {
+		return background;
+	}
+
+	return DEFAULT_LOADING_COLOR;
+};
+
 const isFaviconUrlSecure = (url: string) => {
 	try {
 		const parsedUrl = new URL(url);
@@ -294,18 +324,37 @@ const App = () => {
 
 	const client = useMemo(() => getClientParams(urlParams), [urlParams]);
 
-	const flowProps = {
-		flowId,
-		debug,
-		sendSessionToken,
-		locale,
-		tenant: tenantId,
-		theme,
-		styleId,
-		form,
-		client,
-		onSuccess: (e: CustomEvent<FlowJWTResponse>) => {
+	const showFlowLoading =
+		urlParams.get('loading') === 'true' || env.DESCOPE_FLOW_LOADING === 'true';
+
+	const loadingSpinnerColor = useMemo(
+		() =>
+			getLoadingSpinnerColor({
+				loadingColor: normalizeBackgroundParam(
+					urlParams.get('loading_color') || env.DESCOPE_LOADING_COLOR
+				),
+				background
+			}),
+		[urlParams, background]
+	);
+
+	const showFlow = !done && Boolean(projectId && flowId);
+	const flowSessionKey = `${projectId}:${flowId}`;
+	const [readyFlowKey, setReadyFlowKey] = useState<string | null>(null);
+	const isFlowReady = readyFlowKey === flowSessionKey;
+
+	const handleFlowReady = useCallback(() => {
+		setReadyFlowKey(flowSessionKey);
+	}, [flowSessionKey]);
+
+	const handleFlowError = useCallback(() => {
+		setReadyFlowKey(flowSessionKey);
+	}, [flowSessionKey]);
+
+	const handleFlowSuccess = useCallback(
+		(e: CustomEvent<FlowJWTResponse>) => {
 			if (flowId === 'saml-config' || flowId === 'sso-config') {
+				setReadyFlowKey(null);
 				let search = window?.location.search;
 				if (search) {
 					search = `${search}&done=true`;
@@ -320,10 +369,27 @@ const App = () => {
 				return;
 			}
 			if (e?.detail?.flowOutput?.onSuccessRedirectUrl) {
+				setReadyFlowKey(null);
 				// make sure to validate the URL in the flow against approved domains
 				window?.location.assign(e?.detail?.flowOutput?.onSuccessRedirectUrl);
 			}
 		},
+		[flowId]
+	);
+
+	const flowProps = {
+		flowId,
+		debug,
+		sendSessionToken,
+		locale,
+		tenant: tenantId,
+		theme,
+		styleId,
+		form,
+		client,
+		onReady: handleFlowReady,
+		onError: handleFlowError,
+		onSuccess: handleFlowSuccess,
 		...((flowId === 'saml-config' || flowId === 'sso-config') && {
 			autoFocus: false
 		})
@@ -337,14 +403,17 @@ const App = () => {
 			persistTokens={persistTokens}
 		>
 			<div className="app" style={bodyCss} data-testid="app">
-				{!done && projectId && flowId && (
+				{showFlow && showFlowLoading && !isFlowReady && (
+					<FlowLoadingOverlay color={loadingSpinnerColor} />
+				)}
+				{showFlow && (
 					<div
 						className={containerClasses}
 						style={containerCss}
 						data-testid="descope-component"
 					>
 						<FlowGate baseUrl={baseUrl} projectId={projectId}>
-							<Descope {...flowProps} />
+							<Descope key={flowSessionKey} {...flowProps} />
 						</FlowGate>
 					</div>
 				)}

src/components/FlowLoadingOverlay.tsx

@@ -0,0 +1,32 @@
+import React, { CSSProperties } from 'react';
+import '../App.css';
+
+type FlowLoadingOverlayProps = {
+	color: string;
+};
+
+const FlowLoadingOverlay = ({ color }: FlowLoadingOverlayProps) => {
+	const spinnerStyle = {
+		'--flow-loading-color': color
+	} as CSSProperties;
+
+	return (
+		<div
+			className="flow-loading-overlay"
+			data-testid="flow-loading-overlay"
+			role="status"
+			aria-live="polite"
+			aria-busy="true"
+			aria-label="Loading"
+		>
+			<div
+				className="flow-loading-spinner"
+				style={spinnerStyle}
+				data-testid="flow-loading-spinner"
+				aria-hidden="true"
+			/>
+		</div>
+	);
+};
+
+export default FlowLoadingOverlay;