Accessibility fixes for ToggleSwitch (#4744)

TylerJDev · camertron · joshblack · web-flow · commit 3c9e322c58b8 · 2025-08-04T19:30:40.000Z
Co-authored-by: Cameron Dutro &lt;camertron@gmail.com&gt;
Co-authored-by: Josh Black &lt;joshblack@github.com&gt;
diff --git a/.changeset/honest-gorillas-drive.md b/.changeset/honest-gorillas-drive.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Address additional ToggleSwitch a11y feedback
diff --git a/packages/react/src/ToggleSwitch/ToggleSwitch.docs.json b/packages/react/src/ToggleSwitch/ToggleSwitch.docs.json
@@ -95,6 +95,18 @@
       "defaultValue": "'start'",
       "description": "Whether the \"on\" and \"off\" labels should appear before or after the switch.\n\n**This should only be changed when the switch's alignment needs to be adjusted.** For example: It needs to be left-aligned because the label appears above it and the caption appears below it."
     },
+    {
+      "name": "loadingLabelDelay",
+      "type": "number",
+      "defaultValue": "2000",
+      "description": "When the switch is in the loading state, this value controls the amount of delay in milliseconds before the word \"Loading\" is announced to screen readers."
+    },
+    {
+      "name": "loadingLabel",
+      "type": "string",
+      "defaultValue": "'Loading'",
+      "description": "The text that is announced to AT such as screen readers when the switch is in a loading state."
+    },
     {
       "name": "buttonType",
       "type": "'button' | 'submit' | 'reset'",
diff --git a/packages/react/src/ToggleSwitch/ToggleSwitch.features.stories.tsx b/packages/react/src/ToggleSwitch/ToggleSwitch.features.stories.tsx
@@ -1,4 +1,5 @@
-import React from 'react'
+import React, {useState} from 'react'
+import {useSafeTimeout} from '..'
 import ToggleSwitch from './ToggleSwitch'
 import {action} from 'storybook/actions'
 import ToggleSwitchStoryWrapper from './ToggleSwitchStoryWrapper'
@@ -68,6 +69,65 @@ export const Loading = () => (
   </ToggleSwitchStoryWrapper>
 )
 
+type LoadingWithDelayProps = {
+  loadingDelay: number
+  loadingLabelDelay: number
+}
+
+export const LoadingWithDelay = (args: LoadingWithDelayProps) => {
+  const {loadingDelay, loadingLabelDelay} = args
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [timeoutId, setTimeoutId] = useState<number | null>(null)
+  const [toggleState, setToggleState] = useState(false)
+
+  const {safeSetTimeout, safeClearTimeout} = useSafeTimeout()
+
+  const handleToggleClick = () => {
+    setIsLoading(true)
+
+    if (timeoutId) {
+      safeClearTimeout(timeoutId)
+      setTimeoutId(null)
+    }
+
+    setTimeoutId(safeSetTimeout(() => setIsLoading(false), loadingDelay) as unknown as number)
+  }
+
+  return (
+    <ToggleSwitchStoryWrapper>
+      <span id="toggle" style={{fontWeight: 'bold', fontSize: 'var(--base-size-14)'}}>
+        Enable feature
+      </span>
+      <ToggleSwitch
+        loading={isLoading}
+        loadingLabel={`${toggleState ? 'Enabling' : 'Disabling'} feature`}
+        loadingLabelDelay={loadingLabelDelay}
+        aria-labelledby="toggle"
+        onClick={handleToggleClick}
+        onChange={(on: boolean) => setToggleState(on)}
+      />
+    </ToggleSwitchStoryWrapper>
+  )
+}
+
+LoadingWithDelay.args = {
+  loadingDelay: 5000,
+  loadingLabelDelay: 2000,
+}
+LoadingWithDelay.argTypes = {
+  loadingDelay: {
+    control: {
+      type: 'number',
+    },
+  },
+  loadingLabelDelay: {
+    control: {
+      type: 'number',
+    },
+  },
+}
+
 export const LabelEnd = () => (
   <ToggleSwitchStoryWrapper>
     <span id="toggle" className={styles.ToggleLabel}>
diff --git a/packages/react/src/ToggleSwitch/ToggleSwitch.figma.tsx b/packages/react/src/ToggleSwitch/ToggleSwitch.figma.tsx
@@ -21,7 +21,13 @@ figma.connect(
       }),
     },
     example: ({size, checked, labelposition, loading}) => (
-      <ToggleSwitch size={size} checked={checked} statusLabelPosition={labelposition} loading={loading} />
+      <ToggleSwitch
+        aria-labelledby=""
+        size={size}
+        checked={checked}
+        statusLabelPosition={labelposition}
+        loading={loading}
+      />
     ),
   },
 )
diff --git a/packages/react/src/ToggleSwitch/ToggleSwitch.test.tsx b/packages/react/src/ToggleSwitch/ToggleSwitch.test.tsx
@@ -1,6 +1,6 @@
 import {describe, expect, it, vi} from 'vitest'
 import React from 'react'
-import {render} from '@testing-library/react'
+import {render, waitFor} from '@testing-library/react'
 import ToggleSwitch from './'
 import userEvent from '@testing-library/user-event'
 
@@ -46,7 +46,7 @@ describe('ToggleSwitch', () => {
     expect(toggleSwitch).toHaveAttribute('aria-pressed', 'false')
   })
 
-  it("renders a switch who's state is loading", async () => {
+  it('renders a switch whose state is loading', async () => {
     const user = userEvent.setup()
     const {getByLabelText, container} = render(
       <>
@@ -94,6 +94,22 @@ describe('ToggleSwitch', () => {
     expect(toggleSwitch).toHaveAttribute('aria-pressed', 'true')
   })
 
+  it('ensures the status label cannot toggle a disabled switch', async () => {
+    const user = userEvent.setup()
+    const {getByLabelText, getByText} = render(
+      <>
+        <div id="switchLabel">{SWITCH_LABEL_TEXT}</div>
+        <ToggleSwitch aria-labelledby="switchLabel" disabled />
+      </>,
+    )
+    const toggleSwitch = getByLabelText(SWITCH_LABEL_TEXT)
+    const toggleSwitchStatusLabel = getByText('Off')
+
+    expect(toggleSwitch).toHaveAttribute('aria-pressed', 'false')
+    await user.click(toggleSwitchStatusLabel)
+    expect(toggleSwitch).toHaveAttribute('aria-pressed', 'false')
+  })
+
   it('switches from off to on with a controlled prop', async () => {
     const user = userEvent.setup()
     const ControlledSwitchComponent = () => {
@@ -157,6 +173,18 @@ describe('ToggleSwitch', () => {
     expect(toggleSwitch).toBeInTheDocument()
   })
 
+  it('renders a switch that has button type button', () => {
+    const {getByLabelText} = render(
+      <>
+        <div id="switchLabel">{SWITCH_LABEL_TEXT}</div>
+        <ToggleSwitch aria-labelledby="switchLabel" />
+      </>,
+    )
+
+    const toggleSwitch = getByLabelText(SWITCH_LABEL_TEXT)
+    expect(toggleSwitch).toHaveAttribute('type', 'button')
+  })
+
   it('supports a `ref` on the inner <button> element', () => {
     const ref = vi.fn()
 
@@ -171,15 +199,17 @@ describe('ToggleSwitch', () => {
     expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
   })
 
-  it('renders a switch that has button type button', () => {
-    const {getByLabelText} = render(
+  it('displays a loading label', async () => {
+    const TEST_ID = 'a test id'
+
+    const {getByTestId} = render(
       <>
-        <div id="switchLabel">{SWITCH_LABEL_TEXT}</div>
-        <ToggleSwitch aria-labelledby="switchLabel" />
+        <span id="label">label</span>
+        <ToggleSwitch data-testid={TEST_ID} aria-labelledby="label" loadingLabelDelay={0} loading />
       </>,
     )
 
-    const toggleSwitch = getByLabelText(SWITCH_LABEL_TEXT)
-    expect(toggleSwitch).toHaveAttribute('type', 'button')
+    const toggleSwitch = getByTestId(TEST_ID)
+    await waitFor(() => expect(toggleSwitch).toHaveTextContent('Loading'))
   })
 })
diff --git a/packages/react/src/ToggleSwitch/ToggleSwitch.tsx b/packages/react/src/ToggleSwitch/ToggleSwitch.tsx
@@ -6,16 +6,21 @@ import Box from '../Box'
 import Spinner from '../Spinner'
 import Text from '../Text'
 import {get} from '../constants'
-import {useProvidedStateOrCreate} from '../hooks'
+import {useProvidedStateOrCreate, useId} from '../hooks'
 import type {BetterSystemStyleObject, SxProp} from '../sx'
 import sx from '../sx'
 import getGlobalFocusStyles from '../internal/utils/getGlobalFocusStyles'
+import VisuallyHidden from '../_VisuallyHidden'
 import type {CellAlignment} from '../DataTable/column'
+import {AriaStatus} from '../live-region'
+import useSafeTimeout from '../hooks/useSafeTimeout'
 
 const TRANSITION_DURATION = '80ms'
 const EASE_OUT_QUAD_CURVE = 'cubic-bezier(0.5, 1, 0.89, 1)'
 
 export interface ToggleSwitchProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>, SxProp {
+  /** The id of the DOM node that labels the switch */
+  ['aria-labelledby']: string
   /** Uncontrolled - whether the switch is turned on */
   defaultChecked?: boolean
   /** Whether the switch is ready for user input */
@@ -34,6 +39,16 @@ export interface ToggleSwitchProps extends Omit<React.HTMLAttributes<HTMLDivElem
    * **This should only be changed when the switch's alignment needs to be adjusted.** For example: It needs to be left-aligned because the label appears above it and the caption appears below it.
    */
   statusLabelPosition?: CellAlignment
+  /**
+   * If the switch is in the loading state, this value controls the amount of delay in milliseconds before
+   * the `loadingLabel` is announced to screen readers.
+   * @default 2000
+   */
+  loadingLabelDelay?: number
+  /** The text to describe what is loading. It should be descriptive and not verbose.
+   * This is primarily used for AT (screen readers) to convey what is currently loading.
+   */
+  loadingLabel?: string
   /** type of button to account for behavior when added to a form*/
   buttonType?: 'button' | 'submit' | 'reset'
 }
@@ -122,7 +137,7 @@ const SwitchButton = styled.button<SwitchButtonProps>`
     }
   }
 
-  &:hover:not(:disabled),
+  &:hover:not(:disabled):not([aria-disabled='true']),
   &:focus:focus-visible {
     background-color: ${get('colors.switchTrack.hoverBg')};
   }
@@ -133,8 +148,12 @@ const SwitchButton = styled.button<SwitchButtonProps>`
   }
 
   ${props => {
-    if (props.disabled) {
+    if (props['aria-disabled']) {
       return css`
+        @media (forced-colors: active) {
+          border-color: GrayText;
+        }
+
         background-color: ${get('colors.switchTrack.disabledBg')};
         border-color: transparent;
         cursor: not-allowed;
@@ -147,7 +166,7 @@ const SwitchButton = styled.button<SwitchButtonProps>`
         background-color: ${get('colors.switchTrack.checked.bg')};
         border-color: var(--control-checked-borderColor-rest, transparent);
 
-        &:hover:not(:disabled),
+        &:hover:not(:disabled):not([aria-disabled='true']),
         &:focus:focus-visible {
           background-color: ${get('colors.switchTrack.checked.hoverBg')};
         }
@@ -172,11 +191,12 @@ const SwitchButton = styled.button<SwitchButtonProps>`
   ${sx}
   ${sizeVariants}
 `
-const ToggleKnob = styled.div<{checked?: boolean; disabled?: boolean}>`
+const ToggleKnob = styled.div<{checked?: boolean; 'aria-disabled': React.AriaAttributes['aria-disabled']}>`
   background-color: ${get('colors.switchKnob.bg')};
   border-width: 1px;
   border-style: solid;
-  border-color: ${props => (props.disabled ? get('colors.switchTrack.disabledBg') : get('colors.switchKnob.border'))};
+  border-color: ${props =>
+    props['aria-disabled'] ? get('colors.switchTrack.disabledBg') : get('colors.switchKnob.border')};
   border-radius: calc(${get('radii.2')} - 1px); /* -1px to account for 1px border around the control */
   width: 50%;
   position: absolute;
@@ -193,8 +213,12 @@ const ToggleKnob = styled.div<{checked?: boolean; disabled?: boolean}>`
   }
 
   ${props => {
-    if (props.disabled) {
+    if (props['aria-disabled']) {
       return css`
+        @media (forced-colors: active) {
+          color: GrayText;
+        }
+
         border-color: ${get('colors.switchTrack.disabledBg')};
       `
     }
@@ -226,27 +250,50 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
       buttonType = 'button',
       size = 'medium',
       statusLabelPosition = 'start',
+      loadingLabelDelay = 2000,
+      loadingLabel = 'Loading',
       sx: sxProp,
       ...rest
     } = props
     const isControlled = typeof checked !== 'undefined'
     const [isOn, setIsOn] = useProvidedStateOrCreate<boolean>(checked, onChange, Boolean(defaultChecked))
     const acceptsInteraction = !disabled && !loading
+
+    const [isLoadingLabelVisible, setIsLoadingLabelVisible] = React.useState(false)
+    const loadingLabelId = useId('loadingLabel')
+
+    const {safeSetTimeout} = useSafeTimeout()
+
     const handleToggleClick: MouseEventHandler = useCallback(
       e => {
+        if (disabled || loading) return
+
         if (!isControlled) {
           setIsOn(!isOn)
         }
         onClick && onClick(e)
       },
-      [onClick, isControlled, isOn, setIsOn],
+      [disabled, isControlled, loading, onClick, setIsOn, isOn],
     )
 
     useEffect(() => {
-      if (onChange && isControlled) {
+      if (onChange && isControlled && !disabled) {
         onChange(Boolean(checked))
       }
-    }, [onChange, checked, isControlled, buttonType])
+    }, [onChange, checked, isControlled, disabled])
+
+    useEffect(() => {
+      if (!loading && isLoadingLabelVisible) {
+        setIsLoadingLabelVisible(false)
+      } else if (loading && !isLoadingLabelVisible) {
+        safeSetTimeout(() => {
+          setIsLoadingLabelVisible(true)
+        }, loadingLabelDelay)
+      }
+    }, [loading, isLoadingLabelVisible, loadingLabelDelay, safeSetTimeout])
+
+    let switchButtonDescribedBy = loadingLabelId
+    if (ariaDescribedby) switchButtonDescribedBy = `${switchButtonDescribedBy} ${ariaDescribedby}`
 
     return (
       <Box
@@ -256,13 +303,19 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
         sx={sxProp}
         {...rest}
       >
-        {loading ? <Spinner size="small" /> : null}
+        <VisuallyHidden>
+          <AriaStatus announceOnShow id={loadingLabelId}>
+            {isLoadingLabelVisible && loadingLabel}
+          </AriaStatus>
+        </VisuallyHidden>
+
+        {loading ? <Spinner size="small" srText={null} /> : null}
         <Text
           color={acceptsInteraction ? 'fg.default' : 'fg.muted'}
           fontSize={size === 'small' ? 0 : 1}
           mx={2}
           aria-hidden="true"
-          sx={{position: 'relative', cursor: 'pointer'}}
+          sx={{position: 'relative', cursor: acceptsInteraction ? 'pointer' : 'not-allowed'}}
           onClick={handleToggleClick}
         >
           <Box textAlign="right" sx={isOn ? null : hiddenTextStyles}>
@@ -277,11 +330,11 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
           type={buttonType}
           onClick={handleToggleClick}
           aria-labelledby={ariaLabelledby}
-          aria-describedby={ariaDescribedby}
+          aria-describedby={isLoadingLabelVisible || ariaDescribedby ? switchButtonDescribedBy : undefined}
           aria-pressed={isOn}
           checked={isOn}
           size={size}
-          disabled={!acceptsInteraction}
+          aria-disabled={!acceptsInteraction}
         >
           <Box aria-hidden="true" display="flex" alignItems="center" width="100%" height="100%" overflow="hidden">
             <Box
@@ -313,7 +366,7 @@ const ToggleSwitch = React.forwardRef<HTMLButtonElement, React.PropsWithChildren
               <CircleIcon size={size} />
             </Box>
           </Box>
-          <ToggleKnob aria-hidden="true" disabled={!acceptsInteraction} checked={isOn} />
+          <ToggleKnob aria-hidden="true" aria-disabled={!acceptsInteraction} checked={isOn} />
         </SwitchButton>
       </Box>
     )
diff --git a/packages/react/src/live-region/Announce.tsx b/packages/react/src/live-region/Announce.tsx
diff --git a/src/ToggleSwitch/__snapshots__/ToggleSwitch.test.tsx.snap b/src/ToggleSwitch/__snapshots__/ToggleSwitch.test.tsx.snap

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@primer/react': minor
 +---
++
 +Address additional ToggleSwitch a11y feedback