Improve loading state

LauraBeatris · LauraBeatris · commit b9e19dfe64aa · 2026-05-05T00:09:34.000-03:00
diff --git a/packages/ui/src/components/ConfigureSSO/ConfigureSSO.tsx b/packages/ui/src/components/ConfigureSSO/ConfigureSSO.tsx
@@ -3,18 +3,7 @@ import type { __experimental_ConfigureSSOProps } from '@clerk/shared/types';
 import React from 'react';
 
 import { useEnvironment, withCoreUserGuard } from '@/contexts';
-import {
-  Box,
-  Col,
-  descriptors,
-  Flex,
-  Flow,
-  Icon,
-  localizationKeys,
-  Spinner,
-  Text,
-  useAppearance,
-} from '@/customizables';
+import { Box, Col, descriptors, Flex, Flow, Icon, localizationKeys, Text, useAppearance } from '@/customizables';
 import { ApplicationLogo } from '@/elements/ApplicationLogo';
 import { withCardStateProvider } from '@/elements/contexts';
 import { NavBar, NavbarContextProvider } from '@/elements/Navbar';
@@ -126,23 +115,12 @@ const AuthenticatedContent = withCoreUserGuard(() => {
             flex: 1,
           })}
         >
-          {isLoadingEnterpriseConnections ? (
-            <Flex
-              align='center'
-              justify='center'
-              sx={{ flex: 1 }}
-            >
-              <Spinner
-                size='lg'
-                colorScheme='primary'
-                elementDescriptor={descriptors.spinner}
-              />
-            </Flex>
-          ) : (
-            <ConfigureSSOFlowProvider enterpriseConnection={enterpriseConnection}>
-              <ConfigureSSOWizardPanel />
-            </ConfigureSSOFlowProvider>
-          )}
+          <ConfigureSSOFlowProvider
+            enterpriseConnection={enterpriseConnection}
+            isLoading={isLoadingEnterpriseConnections}
+          >
+            <ConfigureSSOWizardPanel />
+          </ConfigureSSOFlowProvider>
         </Col>
       </NavbarContextProvider>
     </ProfileCard.Root>
@@ -156,6 +134,7 @@ const ConfigureSSOWizardPanel = () => {
     <Wizard.Root
       steps={CONFIGURE_SSO_STEPS}
       data={data}
+      isLoading={data.isLoading}
     >
       <Wizard.Header />
       <Wizard.Content />
diff --git a/packages/ui/src/components/ConfigureSSO/ConfigureSSOContext.tsx b/packages/ui/src/components/ConfigureSSO/ConfigureSSOContext.tsx
@@ -18,22 +18,25 @@ export interface ConfigureSSOData {
   enterpriseConnection: EnterpriseConnectionResource | undefined;
 }
 
-export type ConfigureSSOContextValue = ConfigureSSOData;
-
-interface ConfigureSSOFlowProviderProps {
+export interface ConfigureSSOContextValue extends ConfigureSSOData {
   /**
-   * The user's enterprise connection, fetched by the parent so that
-   * the wizard can show a loading state before mounting the panel.
-   * `undefined` when the user has no enterprise connection
+   * `true` while the parent is still fetching the user's enterprise
+   * connection
    */
+  isLoading: boolean;
+}
+
+interface ConfigureSSOFlowProviderProps {
   enterpriseConnection: EnterpriseConnectionResource | undefined;
+  isLoading: boolean;
 }
 
 const ConfigureSSOFlowContext = React.createContext<ConfigureSSOContextValue | null>(null);
 ConfigureSSOFlowContext.displayName = 'ConfigureSSOFlowContext';
 
 export const ConfigureSSOFlowProvider = ({
   enterpriseConnection,
+  isLoading,
   children,
 }: PropsWithChildren<ConfigureSSOFlowProviderProps>): JSX.Element => {
   const { user } = useUser();
@@ -44,8 +47,9 @@ export const ConfigureSSOFlowProvider = ({
     () => ({
       enterpriseConnection,
       domainAlreadyVerified,
+      isLoading,
     }),
-    [enterpriseConnection, domainAlreadyVerified],
+    [enterpriseConnection, domainAlreadyVerified, isLoading],
   );
 
   return <ConfigureSSOFlowContext.Provider value={value}>{children}</ConfigureSSOFlowContext.Provider>;
diff --git a/packages/ui/src/elements/Wizard/Wizard.tsx b/packages/ui/src/elements/Wizard/Wizard.tsx
@@ -1,6 +1,6 @@
 import React from 'react';
 
-import { Badge, Button, descriptors, Flex, Icon, Text, useLocalizations } from '@/customizables';
+import { Badge, Box, Button, descriptors, Flex, Icon, Spinner, Text, useLocalizations } from '@/customizables';
 import { CaretLeft, CaretRight } from '@/icons';
 import { Route, Switch, useRouter } from '@/router';
 
@@ -14,11 +14,17 @@ interface WizardRootProps<TData = unknown> {
    * referenced shape changes, the active step list is recomputed
    */
   data?: TData;
+  /**
+   * `true` while the parent flow is still loading async dependencies.
+   * The header renders a skeleton breadcrumb, the content renders a
+   * centered spinner, and the footer's buttons are disabled
+   */
+  isLoading?: boolean;
   children: React.ReactNode;
 }
 
 const Root = <TData,>(props: WizardRootProps<TData>): JSX.Element => {
-  const { steps, data, children } = props;
+  const { steps, data, isLoading = false, children } = props;
   const router = useRouter();
 
   const activeSteps = React.useMemo(() => steps.filter(s => !s.shouldSkip?.(data as TData)), [steps, data]);
@@ -127,6 +133,7 @@ const Root = <TData,>(props: WizardRootProps<TData>): JSX.Element => {
       currentStep={currentStep}
       innerSteps={innerSteps}
       currentInnerStep={currentInnerStep}
+      isLoading={isLoading}
       goNext={goNext}
       goPrev={goPrev}
       goToStep={goToStep}
@@ -169,7 +176,24 @@ const StepRoutes = <TData,>({ step }: { step: WizardStep<TData> }): JSX.Element
  * doesn't match another main step (e.g. its own inner-step paths)
  */
 const Content = (): JSX.Element | null => {
-  const { activeSteps } = useWizard();
+  const { activeSteps, isLoading } = useWizard();
+
+  if (isLoading) {
+    return (
+      <Flex
+        align='center'
+        justify='center'
+        sx={{ flex: 1 }}
+      >
+        <Spinner
+          size='xs'
+          colorScheme='neutral'
+          elementDescriptor={descriptors.spinner}
+        />
+      </Flex>
+    );
+  }
+
   if (activeSteps.length === 0) {
     return null;
   }
@@ -196,7 +220,7 @@ const Content = (): JSX.Element | null => {
  * are clickable for backwards navigation, future steps are disabled
  */
 const Header = (): JSX.Element => {
-  const { activeSteps, currentIndex, goToStep } = useWizard();
+  const { activeSteps, currentIndex, isLoading, goToStep } = useWizard();
   const { t } = useLocalizations();
 
   return (
@@ -219,47 +243,51 @@ const Header = (): JSX.Element => {
 
         return (
           <React.Fragment key={step.id}>
-            <Button
-              variant='unstyled'
-              isDisabled={!isReachable}
-              onClick={() => {
-                if (isReachable) {
-                  void goToStep(step.id);
-                }
-              }}
-              sx={theme => ({
-                gap: theme.space.$1x5,
-                padding: 0,
-                color: isCurrent ? theme.colors.$colorForeground : theme.colors.$colorMutedForeground,
-              })}
-            >
-              <Flex
-                align='center'
-                justify='center'
+            {isLoading ? (
+              <SkeletonBreadcrumbStep />
+            ) : (
+              <Button
+                variant='unstyled'
+                isDisabled={!isReachable}
+                onClick={() => {
+                  if (isReachable) {
+                    void goToStep(step.id);
+                  }
+                }}
                 sx={theme => ({
-                  width: theme.sizes.$5,
-                  height: theme.sizes.$5,
-                  borderRadius: theme.radii.$circle,
-                  fontSize: theme.fontSizes.$xs,
-                  fontWeight: theme.fontWeights.$semibold,
-                  backgroundColor: isCurrent
-                    ? theme.colors.$colorForeground
-                    : isCompleted
-                      ? theme.colors.$neutralAlpha200
-                      : theme.colors.$neutralAlpha100,
-                  color: isCurrent ? theme.colors.$colorBackground : theme.colors.$colorMutedForeground,
+                  gap: theme.space.$1x5,
+                  padding: 0,
+                  color: isCurrent ? theme.colors.$colorForeground : theme.colors.$colorMutedForeground,
                 })}
               >
-                {index + 1}
-              </Flex>
-              <Text
-                as='span'
-                variant='body'
-                sx={{ fontWeight: 'inherit', color: 'inherit' }}
-              >
-                {label}
-              </Text>
-            </Button>
+                <Flex
+                  align='center'
+                  justify='center'
+                  sx={theme => ({
+                    width: theme.sizes.$5,
+                    height: theme.sizes.$5,
+                    borderRadius: theme.radii.$circle,
+                    fontSize: theme.fontSizes.$xs,
+                    fontWeight: theme.fontWeights.$semibold,
+                    backgroundColor: isCurrent
+                      ? theme.colors.$colorForeground
+                      : isCompleted
+                        ? theme.colors.$neutralAlpha200
+                        : theme.colors.$neutralAlpha100,
+                    color: isCurrent ? theme.colors.$colorBackground : theme.colors.$colorMutedForeground,
+                  })}
+                >
+                  {index + 1}
+                </Flex>
+                <Text
+                  as='span'
+                  variant='body'
+                  sx={{ fontWeight: 'inherit', color: 'inherit' }}
+                >
+                  {label}
+                </Text>
+              </Button>
+            )}
             {index < activeSteps.length - 1 && (
               <Icon
                 icon={CaretRight}
@@ -274,6 +302,30 @@ const Header = (): JSX.Element => {
   );
 };
 
+const SkeletonBreadcrumbStep = (): JSX.Element => (
+  <Flex
+    align='center'
+    sx={t => ({ gap: t.space.$1x5 })}
+  >
+    <Box
+      sx={t => ({
+        width: t.sizes.$5,
+        height: t.sizes.$5,
+        borderRadius: t.radii.$circle,
+        backgroundColor: t.colors.$neutralAlpha100,
+      })}
+    />
+    <Box
+      sx={t => ({
+        width: t.sizes.$16,
+        height: t.space.$3,
+        borderRadius: t.radii.$md,
+        backgroundColor: t.colors.$neutralAlpha100,
+      })}
+    />
+  </Flex>
+);
+
 /**
  * Compact "Step X / Y" badge that tracks the current main step's
  * inner-step progress. Renders nothing when the current step has no
@@ -322,6 +374,12 @@ interface FooterProps {
    * default)
    */
   hidePrevious?: boolean;
+  /**
+   * Force-disables both Previous and Continue regardless of the
+   * wizard's own state. Useful while async dependencies of the flow
+   * are still loading
+   */
+  isDisabled?: boolean;
 }
 
 /**
@@ -330,8 +388,9 @@ interface FooterProps {
  * simply advances to the next step
  */
 const Footer = (props: FooterProps): JSX.Element => {
-  const { previousLabel = 'Previous', continueLabel = 'Continue', hidePrevious = false } = props;
-  const { isFirstStep, isLastStep, goPrev, goNext, continueAction } = useWizard();
+  const { previousLabel = 'Previous', continueLabel = 'Continue', hidePrevious = false, isDisabled = false } = props;
+  const { isFirstStep, isLastStep, isLoading, goPrev, goNext, continueAction } = useWizard();
+  const isForceDisabled = isDisabled || isLoading;
   const { t } = useLocalizations();
 
   const continueLabelToShow =
@@ -367,7 +426,7 @@ const Footer = (props: FooterProps): JSX.Element => {
         <Button
           variant='outline'
           size='sm'
-          isDisabled={isFirstStep}
+          isDisabled={isForceDisabled || isFirstStep}
           onClick={() => void goPrev()}
         >
           <Icon
@@ -381,7 +440,7 @@ const Footer = (props: FooterProps): JSX.Element => {
       <Button
         variant='solid'
         size='sm'
-        isDisabled={continueAction?.isDisabled || isLastStep}
+        isDisabled={isForceDisabled || continueAction?.isDisabled || isLastStep}
         isLoading={continueAction?.isLoading}
         onClick={handleContinue}
       >
diff --git a/packages/ui/src/elements/Wizard/WizardContext.tsx b/packages/ui/src/elements/Wizard/WizardContext.tsx
@@ -18,14 +18,16 @@ interface WizardProviderProps<TData> {
   currentStep: WizardStep<TData> | undefined;
   innerSteps: WizardInnerStep<TData>[];
   currentInnerStep: WizardInnerStep<TData> | undefined;
+  isLoading: boolean;
   goNext: WizardContextValue<TData>['goNext'];
   goPrev: WizardContextValue<TData>['goPrev'];
   goToStep: WizardContextValue<TData>['goToStep'];
   children: React.ReactNode;
 }
 
 export function WizardProvider<TData>(props: WizardProviderProps<TData>): JSX.Element {
-  const { activeSteps, currentStep, innerSteps, currentInnerStep, goNext, goPrev, goToStep, children } = props;
+  const { activeSteps, currentStep, innerSteps, currentInnerStep, isLoading, goNext, goPrev, goToStep, children } =
+    props;
 
   const [continueAction, setContinueAction] = React.useState<ContinueAction | undefined>(undefined);
 
@@ -55,13 +57,14 @@ export function WizardProvider<TData>(props: WizardProviderProps<TData>): JSX.El
       totalInnerSteps,
       isFirstStep,
       isLastStep,
+      isLoading,
       goNext,
       goPrev,
       goToStep,
       continueAction,
       setContinueAction,
     };
-  }, [activeSteps, currentStep, innerSteps, currentInnerStep, goNext, goPrev, goToStep, continueAction]);
+  }, [activeSteps, currentStep, innerSteps, currentInnerStep, isLoading, goNext, goPrev, goToStep, continueAction]);
 
   return <WizardContext.Provider value={value}>{children}</WizardContext.Provider>;
 }
diff --git a/packages/ui/src/elements/Wizard/types.ts b/packages/ui/src/elements/Wizard/types.ts
@@ -152,6 +152,12 @@ export interface WizardContextValue<TData = unknown> {
    * (last main step + last inner step, if any)
    */
   isLastStep: boolean;
+  /**
+   * `true` while the parent flow is still loading async dependencies.
+   * The header renders a skeleton breadcrumb, the content renders a
+   * centered spinner, and the footer's buttons are disabled
+   */
+  isLoading: boolean;
   /**
    * Navigate forward. Within a container step, advances through inner
    * steps first, otherwise (or on the last inner step) advances to
