feat(Spinner): Adds a delay prop to the Spinner component that delays rendering by 1000ms. (#7059)

Author: jonrohan

.changeset/shaggy-pants-remain.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+feat(Spinner): Adds a delay prop to the Spinner component that delays rendering by 1000ms.

packages/react/src/Spinner/Spinner.docs.json

@@ -1,51 +1,60 @@
 {
+  "a11yReviewed": "2025-01-08",
   "id": "spinner",
+  "importPath": "@primer/react",
   "name": "Spinner",
-  "status": "alpha",
-  "a11yReviewed": "2025-01-08",
-  "stories": [
+  "props": [
     {
-      "id": "components-spinner--default"
+      "description": "Sets the width and height of the spinner.",
+      "name": "size",
+      "type": "'small' | 'medium' | 'large'"
     },
     {
-      "id": "components-spinner-features--small"
+      "defaultValue": "Loading",
+      "description": "Sets the text conveyed by assistive technologies such as screen readers. Set to `null` if the loading state is displayed in a text node somewhere else on the page.",
+      "name": "srText",
+      "type": "string | null"
     },
     {
-      "id": "components-spinner-features--large"
+      "deprecated": true,
+      "description": "Sets the text conveyed by assistive technologies such as screen readers.",
+      "name": "aria-label",
+      "type": "string"
     },
     {
-      "id": "components-spinner-features--suppress-screen-reader-text"
+      "defaultValue": "",
+      "description": "",
+      "name": "className",
+      "type": "string"
+    },
+    {
+      "name": "data-*",
+      "type": "string"
+    },
+    {
+      "defaultValue": "false",
+      "description": "Whether to delay the spinner before rendering by the defined 1000ms.",
+      "name": "delay",
+      "type": "boolean"
     }
   ],
-  "importPath": "@primer/react",
-  "props": [
+  "status": "alpha",
+  "stories": [
     {
-      "name": "size",
-      "type": "'small' | 'medium' | 'large'",
-      "description": "Sets the width and height of the spinner."
+      "id": "components-spinner--default"
     },
     {
-      "name": "srText",
-      "type": "string | null",
-      "defaultValue": "Loading",
-      "description": "Sets the text conveyed by assistive technologies such as screen readers. Set to `null` if the loading state is displayed in a text node somewhere else on the page."
+      "id": "components-spinner-features--small"
     },
     {
-      "name": "aria-label",
-      "type": "string",
-      "description": "Sets the text conveyed by assistive technologies such as screen readers.",
-      "deprecated": true
+      "id": "components-spinner-features--large"
     },
     {
-      "name": "className",
-      "type": "string",
-      "description": "",
-      "defaultValue": ""
+      "id": "components-spinner-features--suppress-screen-reader-text"
     },
     {
-      "name": "data-*",
-      "type": "string"
+      "id": "components-spinner-features--with-delay"
     }
   ],
   "subcomponents": []
-}
+}

packages/react/src/Spinner/Spinner.features.stories.tsx

@@ -19,3 +19,5 @@ export const SuppressScreenReaderText = () => (
     <AriaStatus>Loading...</AriaStatus>
   </Stack>
 )
+
+export const WithDelay = () => <Spinner delay />

packages/react/src/Spinner/Spinner.test.tsx

@@ -1,7 +1,8 @@
 import type {SpinnerProps} from '..'
 import {Spinner} from '..'
 import {render, screen} from '@testing-library/react'
-import {describe, expect, it} from 'vitest'
+import {describe, expect, it, vi, beforeEach, afterEach} from 'vitest'
+import {act} from 'react'
 
 describe('Spinner', () => {
   it('should support `className` on the outermost element', () => {
@@ -46,4 +47,53 @@ describe('Spinner', () => {
     expectSize('medium', '32px')
     expectSize('large', '64px')
   })
+
+  describe('delay behavior', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+    })
+
+    afterEach(() => {
+      vi.restoreAllMocks()
+      vi.useRealTimers()
+    })
+
+    it('should render immediately when delay is false', () => {
+      const {container} = render(<Spinner delay={false} />)
+      expect(container.querySelector('svg')).toBeInTheDocument()
+    })
+
+    it('should not render immediately when delay is true', () => {
+      const {container} = render(<Spinner delay={true} />)
+      expect(container.querySelector('svg')).not.toBeInTheDocument()
+    })
+
+    it('should render after 1000ms when delay is true', () => {
+      const {container} = render(<Spinner delay={true} />)
+
+      // Not visible initially
+      expect(container.querySelector('svg')).not.toBeInTheDocument()
+
+      // Advance timers by 1000ms
+      act(() => {
+        vi.advanceTimersByTime(1000)
+      })
+
+      // Now it should be visible
+      expect(container.querySelector('svg')).toBeInTheDocument()
+    })
+
+    it('should cleanup timeout on unmount when delay is true', () => {
+      const {unmount} = render(<Spinner delay={true} />)
+
+      // Unmount before the delay completes
+      unmount()
+
+      // Advance timers to see if there are any side effects
+      vi.advanceTimersByTime(1000)
+
+      // No errors should occur
+      expect(true).toBe(true)
+    })
+  })
 })

packages/react/src/Spinner/Spinner.tsx

@@ -1,4 +1,5 @@
 import type React from 'react'
+import {useState, useEffect} from 'react'
 import {VisuallyHidden} from '../VisuallyHidden'
 import type {HTMLDataAttributes} from '../internal/internal-types'
 import {useId} from '../hooks'
@@ -20,6 +21,8 @@ export type SpinnerProps = {
   'aria-label'?: string
   className?: string
   style?: React.CSSProperties
+  /** Whether to delay the spinner before rendering by the defined 1000ms. */
+  delay?: boolean
 } & HTMLDataAttributes
 
 function Spinner({
@@ -28,12 +31,29 @@ function Spinner({
   'aria-label': ariaLabel,
   className,
   style,
+  delay = false,
   ...props
 }: SpinnerProps) {
   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}>