feat: add support for delay to spinners and skeletons

packages/react/src/Skeleton/SkeletonBox.stories.tsx

@@ -12,6 +12,9 @@ export const Default = () => <SkeletonBox />
 export const Playground: StoryFn<ComponentProps<typeof SkeletonBox>> = args => <SkeletonBox {...args} />
 
 Playground.argTypes = {
+  delay: {
+    type: 'number',
+  },
   height: {
     type: 'string',
   },

packages/react/src/Skeleton/SkeletonBox.tsx

@@ -1,6 +1,8 @@
 import React from 'react'
 import {type CSSProperties, type HTMLProps} from 'react'
 import {clsx} from 'clsx'
+import {useLoadingVisibility} from '../loading'
+import type {LoadingDelay} from '../loading'
 import classes from './SkeletonBox.module.css'
 
 export type SkeletonBoxProps = {
@@ -10,17 +12,26 @@ export type SkeletonBoxProps = {
   width?: CSSProperties['width']
   /** The className of the skeleton box */
   className?: string
-} & HTMLProps<HTMLElement>
+} & LoadingDelay &
+  HTMLProps<HTMLElement>
 
 export const SkeletonBox = React.forwardRef<HTMLElement, SkeletonBoxProps>(function SkeletonBox(
-  {height, width, className, style, ...props},
+  {delay, height, width, className, style, ...props},
   ref,
 ) {
+  const {style: loadingStyle} = useLoadingVisibility(delay)
+  const containerStyle = {
+    height,
+    width,
+    ...loadingStyle,
+    ...style,
+  }
+
   return (
     <div
       ref={ref as React.RefObject<HTMLDivElement>}
       className={clsx(className, classes.SkeletonBox)}
-      style={{height, width, ...(style || {})}}
+      style={containerStyle}
       {...props}
     />
   )

packages/react/src/SkeletonAvatar/SkeletonAvatar.tsx

@@ -1,19 +1,22 @@
+import {clsx} from 'clsx'
 import type React from 'react'
 import {isResponsiveValue} from '../hooks/useResponsiveValue'
 import type {AvatarProps} from '../Avatar'
 import {DEFAULT_AVATAR_SIZE} from '../Avatar/Avatar'
 import {SkeletonBox} from '../Skeleton'
+import {useLoadingVisibility} from '../loading'
+import type {LoadingDelay} from '../loading'
 import classes from './SkeletonAvatar.module.css'
-import {clsx} from 'clsx'
 
-interface SkeletonAvatarProps extends Omit<React.HTMLProps<HTMLElement>, 'size'> {
+interface SkeletonAvatarProps extends Omit<React.HTMLProps<HTMLElement>, 'size'>, LoadingDelay {
   /** Class name for custom styling */
   className?: string
   size?: AvatarProps['size']
   square?: AvatarProps['square']
 }
 
-function SkeletonAvatar({size = DEFAULT_AVATAR_SIZE, square, className, style, ...rest}: SkeletonAvatarProps) {
+function SkeletonAvatar({delay, size = DEFAULT_AVATAR_SIZE, square, className, style, ...rest}: SkeletonAvatarProps) {
+  const {style: loadingStyle} = useLoadingVisibility(delay)
   const responsive = isResponsiveValue(size)
   const cssSizeVars = {} as Record<string, string>
 
@@ -32,7 +35,7 @@ function SkeletonAvatar({size = DEFAULT_AVATAR_SIZE, square, className, style, .
       data-component="SkeletonAvatar"
       data-responsive={responsive ? '' : undefined}
       data-square={square ? '' : undefined}
-      style={{...(style || {}), ...cssSizeVars}}
+      style={{...style, ...cssSizeVars, ...loadingStyle}}
     />
   )
 }

packages/react/src/SkeletonText/SkeletonText.tsx

@@ -1,10 +1,12 @@
+import {clsx} from 'clsx'
 import type React from 'react'
 import {type HTMLProps} from 'react'
-import classes from './SkeletonText.module.css'
-import {clsx} from 'clsx'
 import {SkeletonBox} from '../Skeleton'
+import classes from './SkeletonText.module.css'
+import {useLoadingVisibility} from '../loading'
+import type {LoadingDelay} from '../loading'
 
-interface SkeletonTextProps extends Omit<HTMLProps<HTMLElement>, 'size'> {
+interface SkeletonTextProps extends Omit<HTMLProps<HTMLElement>, 'size'>, LoadingDelay {
   /** Size of the text that the skeleton is replacing. */
   size?: 'display' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall' | 'subtitle'
   /** Number of lines of skeleton text to render. */
@@ -15,7 +17,9 @@ interface SkeletonTextProps extends Omit<HTMLProps<HTMLElement>, 'size'> {
   className?: string
 }
 
-function SkeletonText({lines = 1, maxWidth, size = 'bodyMedium', className, style, ...rest}: SkeletonTextProps) {
+function SkeletonText({delay, lines = 1, maxWidth, size = 'bodyMedium', className, style, ...rest}: SkeletonTextProps) {
+  const {style: loadingStyle} = useLoadingVisibility(delay)
+
   if (lines < 2) {
     return (
       <SkeletonBox
@@ -25,6 +29,7 @@ function SkeletonText({lines = 1, maxWidth, size = 'bodyMedium', className, styl
         className={clsx(className, classes.SkeletonText)}
         style={{
           ...style,
+          ...loadingStyle,
           maxWidth,
         }}
         {...rest}
@@ -38,6 +43,7 @@ function SkeletonText({lines = 1, maxWidth, size = 'bodyMedium', className, styl
       className={classes.SkeletonTextWrapper}
       style={{
         ...style,
+        ...loadingStyle,
         maxWidth,
       }}
     >

packages/react/src/Spinner/Spinner.tsx

@@ -1,12 +1,14 @@
 import {clsx} from 'clsx'
 import type React from 'react'
-import {useCallback, useEffect, useRef, useState, useSyncExternalStore} from 'react'
+import {useCallback, useRef, useSyncExternalStore} from 'react'
 import {VisuallyHidden} from '../VisuallyHidden'
 import type {HTMLDataAttributes} from '../internal/internal-types'
 import {useId} from '../hooks'
 import classes from './Spinner.module.css'
 import {useMedia} from '../hooks/useMedia'
 import {useFeatureFlag} from '../FeatureFlags'
+import {useLoadingVisibility} from '../loading'
+import type {LoadingDelay} from '../loading'
 
 const sizeMap = {
   small: '16px',
@@ -25,7 +27,8 @@ export type SpinnerProps = {
   style?: React.CSSProperties
   /** Whether to delay the spinner before rendering by the defined 1000ms. */
   delay?: boolean
-} & HTMLDataAttributes
+} & LoadingDelay &
+  HTMLDataAttributes
 
 function Spinner({
   size: sizeKey = 'medium',
@@ -38,26 +41,11 @@ function Spinner({
 }: SpinnerProps) {
   const syncAnimationsEnabled = useFeatureFlag('primer_react_spinner_synchronize_animations')
   const animationRef = useSpinnerAnimation()
+  const {style: loadingStyle} = useLoadingVisibility(delay)
   const size = sizeMap[sizeKey]
   const hasHiddenLabel = srText !== null && ariaLabel === undefined
   const labelId = useId()
 
-  const [isVisible, setIsVisible] = useState(!delay)
-
-  useEffect(() => {
-    if (delay) {
-      const timeoutId = setTimeout(() => {
-        setIsVisible(true)
-      }, 1000)
-
-      return () => clearTimeout(timeoutId)
-    }
-  }, [delay])
-
-  if (!isVisible) {
-    return null
-  }
-
   return (
     /* inline-flex removes the extra line height */
     <span className={classes.Box}>
@@ -71,7 +59,10 @@ function Spinner({
         aria-label={ariaLabel ?? undefined}
         aria-labelledby={hasHiddenLabel ? labelId : undefined}
         className={clsx(className, classes.SpinnerAnimation)}
-        style={style}
+        style={{
+          ...style,
+          ...loadingStyle,
+        }}
         {...props}
       >
         <circle

packages/react/src/loading.ts

@@ -0,0 +1,40 @@
+import {useEffect, useState, type CSSProperties} from 'react'
+
+type LoadingDelay = {
+  /**
+   * Apply a delay to a loading state. When true, applies a default delay of 1000ms. When a number is provided, applies that number (in milliseconds) as the delay.
+   */
+  delay?: boolean | number
+}
+
+const DEFAULT_DELAY_MS = 1000
+
+function useLoadingVisibility(delay: LoadingDelay['delay']): {style: CSSProperties} {
+  const [visible, setVisible] = useState(delay === undefined || delay === false)
+  const style: CSSProperties = {
+    animation: visible ? undefined : 'none',
+    visibility: visible ? undefined : 'hidden',
+  }
+
+  useEffect(() => {
+    if (delay === undefined || delay === false) {
+      return
+    }
+
+    const delayMs = typeof delay === 'number' ? delay : DEFAULT_DELAY_MS
+    const timeoutId = setTimeout(() => {
+      setVisible(true)
+    }, delayMs)
+
+    return () => {
+      clearTimeout(timeoutId)
+    }
+  }, [delay])
+
+  return {
+    style,
+  }
+}
+
+export {useLoadingVisibility}
+export type {LoadingDelay}