fix(ui): Improve members notification badge loading experience

.changeset/skeleton-members-badge-loading.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': minor
+---
+
+Add a `Skeleton` loading placeholder with a subtle shimmer, targetable via the new `skeleton` appearance descriptor. The Organization Profile members tabs now reserve space for their notification count badges while loading, so the tabs no longer shift when the counts appear.

packages/ui/src/common/NotificationCountBadge.tsx

@@ -1,6 +1,7 @@
 import { formatToCompactNumber } from '@/utils/intl';
 
 import { Flex, localizationKeys, NotificationBadge, useLocalizations } from '../customizables';
+import { Skeleton } from '../elements/Skeleton';
 import { usePrefersReducedMotion } from '../hooks';
 import type { PropsOfComponent, ThemableCssProp } from '../styledSystem';
 import { animations } from '../styledSystem';
@@ -9,10 +10,11 @@ type NotificationCountBadgeProps = PropsOfComponent<typeof NotificationBadge> &
   notificationCount: number;
   containerSx?: ThemableCssProp;
   shouldAnimate?: boolean;
+  isLoading?: boolean;
 };
 
 export const NotificationCountBadge = (props: NotificationCountBadgeProps) => {
-  const { notificationCount, containerSx, shouldAnimate = true, ...restProps } = props;
+  const { notificationCount, containerSx, shouldAnimate = true, isLoading = false, ...restProps } = props;
   const prefersReducedMotion = usePrefersReducedMotion();
   const { t } = useLocalizations();
   const localeKey = t(localizationKeys('locale'));
@@ -37,12 +39,22 @@ export const NotificationCountBadge = (props: NotificationCountBadgeProps) => {
         containerSx,
       ]}
     >
-      <NotificationBadge
-        sx={enterExitAnimation}
-        {...restProps}
-      >
-        {formattedNotificationCount}
-      </NotificationBadge>
+      {isLoading ? (
+        <Skeleton
+          sx={t => ({
+            height: t.space.$4,
+            width: t.space.$5,
+            borderRadius: t.radii.$lg,
+          })}
+        />
+      ) : (
+        <NotificationBadge
+          sx={enterExitAnimation}
+          {...restProps}
+        >
+          {formattedNotificationCount}
+        </NotificationBadge>
+      )}
     </Flex>
   );
 };

packages/ui/src/components/OrganizationProfile/OrganizationMembers.tsx

@@ -84,37 +84,36 @@ export const OrganizationMembers = withCardStateProvider(() => {
               <TabsList sx={t => ({ gap: t.space.$2 })}>
                 {canReadMemberships && (
                   <Tab localizationKey={localizationKeys('organizationProfile.membersPage.start.headerTitle__members')}>
-                    {!!memberships?.count && (
-                      <NotificationCountBadge
-                        shouldAnimate={!query}
-                        notificationCount={memberships.count}
-                        colorScheme='outline'
-                      />
-                    )}
+                    <NotificationCountBadge
+                      shouldAnimate={false}
+                      isLoading={!memberships?.data || memberships.isLoading}
+                      notificationCount={memberships?.count ?? 0}
+                      colorScheme='outline'
+                    />
                   </Tab>
                 )}
                 {canManageMemberships && (
                   <Tab
                     localizationKey={localizationKeys('organizationProfile.membersPage.start.headerTitle__invitations')}
                   >
-                    {invitations?.data && !invitations.isLoading && (
-                      <NotificationCountBadge
-                        notificationCount={invitations.count}
-                        colorScheme='outline'
-                      />
-                    )}
+                    <NotificationCountBadge
+                      shouldAnimate={false}
+                      isLoading={!invitations?.data || invitations.isLoading}
+                      notificationCount={invitations?.count ?? 0}
+                      colorScheme='outline'
+                    />
                   </Tab>
                 )}
                 {canManageMemberships && isDomainsEnabled && (
                   <Tab
                     localizationKey={localizationKeys('organizationProfile.membersPage.start.headerTitle__requests')}
                   >
-                    {membershipRequests?.data && !membershipRequests.isLoading && (
-                      <NotificationCountBadge
-                        notificationCount={membershipRequests.count}
-                        colorScheme='outline'
-                      />
-                    )}
+                    <NotificationCountBadge
+                      shouldAnimate={false}
+                      isLoading={!membershipRequests?.data || membershipRequests.isLoading}
+                      notificationCount={membershipRequests?.count ?? 0}
+                      colorScheme='outline'
+                    />
                   </Tab>
                 )}
               </TabsList>

packages/ui/src/customizables/elementDescriptors.ts

@@ -510,6 +510,7 @@ export const APPEARANCE_KEYS = containsAllElementsConfigKeys([
   'notificationBadge',
   'buttonArrowIcon',
   'spinner',
+  'skeleton',
 
   'apiKeys',
   'apiKeysHeader',

packages/ui/src/elements/Skeleton.tsx

@@ -0,0 +1,59 @@
+import { Box, descriptors } from '../customizables';
+import { usePrefersReducedMotion } from '../hooks';
+import type { PropsOfComponent } from '../styledSystem';
+import { animations } from '../styledSystem';
+
+type SkeletonProps = PropsOfComponent<typeof Box> & {
+  /** When false, render children as-is instead of the loading placeholder. Defaults to true. */
+  show?: boolean;
+};
+
+/**
+ * Decorative placeholder for loading states with a subtle shimmer. Two modes:
+ *
+ * - **Block** — `<Skeleton sx={{ width, height }} />` reserves space with a plain bar.
+ * - **Content** — `<Skeleton><Button /></Skeleton>` sizes to the wrapped children (rendered
+ *   invisibly) so the placeholder matches the real content and nothing shifts on load.
+ *
+ * Pass `show={false}` to render the children normally. Targetable via the `skeleton` descriptor.
+ */
+export const Skeleton = (props: SkeletonProps) => {
+  const { show = true, sx, children, ...rest } = props;
+  const prefersReducedMotion = usePrefersReducedMotion();
+
+  if (!show) {
+    return <>{children}</>;
+  }
+
+  return (
+    <Box
+      as='span'
+      aria-hidden
+      elementDescriptor={descriptors.skeleton}
+      sx={[
+        t => ({
+          position: 'relative',
+          display: children ? 'inline-block' : 'block',
+          overflow: 'hidden',
+          borderRadius: t.radii.$md,
+          backgroundColor: t.colors.$neutralAlpha100,
+          '> *': { visibility: 'hidden' },
+          '::after': {
+            content: '""',
+            position: 'absolute',
+            inset: 0,
+            backgroundImage: `linear-gradient(90deg, ${t.colors.$transparent} 0%, ${t.colors.$neutralAlpha50} 50%, ${t.colors.$transparent} 100%)`,
+            backgroundSize: '200% 100%',
+            animation: prefersReducedMotion
+              ? 'none'
+              : `${animations.loadingShimmer} 1.5s ${t.transitionTiming.$slowBezier} infinite`,
+          },
+        }),
+        sx,
+      ]}
+      {...rest}
+    >
+      {children}
+    </Box>
+  );
+};

packages/ui/src/internal/appearance.ts

@@ -646,6 +646,7 @@ export type ElementsConfig = {
   notificationBadge: WithOptions;
   buttonArrowIcon: WithOptions;
   spinner: WithOptions;
+  skeleton: WithOptions;
 
   apiKeys: WithOptions;
   apiKeysHeader: WithOptions;

packages/ui/src/styledSystem/animations.ts

@@ -38,6 +38,11 @@ const fadeOut = keyframes`
   100% { opacity: 0; }
 `;
 
+const loadingShimmer = keyframes`
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+`;
+
 const inAnimation = keyframes`
   0% {
     opacity: 0;
@@ -143,4 +148,5 @@ export const animations = {
   inDelayAnimation,
   outAnimation,
   notificationAnimation,
+  loadingShimmer,
 };