feat: Conditional image sources (#9335)

devongovett · web-flow · commit 810a385959e1 · 2025-12-11T23:18:43.000Z
* feat: Conditional image sources

* Fix
diff --git a/packages/@react-spectrum/s2/src/Image.tsx b/packages/@react-spectrum/s2/src/Image.tsx
@@ -1,3 +1,4 @@
+import {ColorSchemeContext} from './Provider';
 import {ContextValue, SlotProps} from 'react-aria-components';
 import {createContext, ForwardedRef, forwardRef, HTMLAttributeReferrerPolicy, JSX, ReactNode, useCallback, useContext, useMemo, useReducer, useRef, version} from 'react';
 import {DefaultImageGroup, ImageGroup} from './ImageCoordinator';
@@ -9,9 +10,46 @@ import {UnsafeStyles} from './style-utils';
 import {useLayoutEffect} from '@react-aria/utils';
 import {useSpectrumContextProps} from './useSpectrumContextProps';
 
+export interface ImageSource {
+  /**
+   * A comma-separated list of image URLs and descriptors.
+   * [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source#srcset).
+   */
+  srcSet?: string | undefined,
+  /**
+   * The color scheme for this image source. Unlike `media`, this respects the `Provider` color scheme setting.
+   */
+  colorScheme?: 'light' | 'dark',
+  /**
+   * A media query describing when the source should render.
+   * [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source#media).
+   */
+  media?: string | undefined,
+  /**
+   * A list of source sizes that describe the final rendered width of the image.
+   * [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source#sizes).
+   */
+  sizes?: string | undefined,
+  /**
+   * The mime type of the image.
+   * [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source#type).
+   */
+  type?: string | undefined,
+  /**
+   * The intrinsic width of the image.
+   * [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source#width).
+   */
+  width?: number,
+  /**
+   * The intrinsic height of the image.
+   * [See MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source#height).
+   */
+  height?: number
+}
+
 export interface ImageProps extends UnsafeStyles, SlotProps {
-  /** The URL of the image. */
-  src?: string,
+  /** The URL of the image or a list of conditional sources. */
+  src?: string | ImageSource[],
   // TODO
   // srcSet?: string,
   // sizes?: string,
@@ -61,10 +99,6 @@ export interface ImageProps extends UnsafeStyles, SlotProps {
    * If not provided, the default image group is used.
    */
   group?: ImageGroup,
-  /**
-   * Child `<source>` elements defining alternate versions of an image for different display/device scenarios.
-   */
-  children?: ReactNode,
   /**
    * Associates the image with a microdata object.
    * See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/itemprop).
@@ -159,7 +193,7 @@ export const Image = forwardRef(function Image(props: ImageProps, domRef: Forwar
   [props, domRef] = useSpectrumContextProps(props, domRef, ImageContext);
 
   let {
-    src = '',
+    src: srcProp = '',
     styles,
     UNSAFE_className = '',
     UNSAFE_style,
@@ -177,16 +211,17 @@ export const Image = forwardRef(function Image(props: ImageProps, domRef: Forwar
     slot,
     width,
     height,
-    children,
     itemProp
   } = props;
   let hidden = (props as ImageContextValue).hidden;
+  let colorScheme = useContext(ColorSchemeContext);
+  let cacheKey = useMemo(() => typeof srcProp === 'object' ? JSON.stringify(srcProp) : srcProp, [srcProp]);
   
   let {revealAll, register, unregister, load} = useContext(group);
-  let [{state, src: lastSrc, loadTime}, dispatch] = useReducer(reducer, src, createState);
+  let [{state, src: lastCacheKey, loadTime}, dispatch] = useReducer(reducer, cacheKey, createState);
 
-  if (src !== lastSrc && !hidden) {
-    dispatch({type: 'update', src});
+  if (cacheKey !== lastCacheKey && !hidden) {
+    dispatch({type: 'update', src: cacheKey});
   }
 
   if (state === 'loaded' && revealAll && !hidden) {
@@ -199,21 +234,21 @@ export const Image = forwardRef(function Image(props: ImageProps, domRef: Forwar
       return;
     }
 
-    register(src);
+    register(cacheKey);
     return () => {
-      unregister(src);
+      unregister(cacheKey);
     };
-  }, [hidden, register, unregister, src]);
+  }, [hidden, register, unregister, cacheKey]);
 
   let onLoad = useCallback(() => {
-    load(src);
+    load(cacheKey);
     dispatch({type: 'loaded'});
-  }, [load, src]);
+  }, [load, cacheKey]);
 
   let onError = useCallback(() => {
     dispatch({type: 'error'});
-    unregister(src);
-  }, [unregister, src]);
+    unregister(cacheKey);
+  }, [unregister, cacheKey]);
 
   let isSkeleton = useIsSkeleton();
   let isAnimating = isSkeleton || state === 'loading' || state === 'loaded';
@@ -223,15 +258,20 @@ export const Image = forwardRef(function Image(props: ImageProps, domRef: Forwar
       return;
     }
 
+    // In React act environments, run immediately.
+    // @ts-ignore
+    let isTestEnv = typeof IS_REACT_ACT_ENVIRONMENT === 'boolean' ? IS_REACT_ACT_ENVIRONMENT : typeof jest !== 'undefined';
+    let runTask = isTestEnv ? fn => fn() : queueMicrotask;
+
     // If the image is already loaded, update state immediately instead of waiting for onLoad.
     let img = imgRef.current;
     if (state === 'loading' && img?.complete) {
       if (img.naturalWidth === 0 && img.naturalHeight === 0) {
         // Queue a microtask so we don't hit React's update limit.
         // TODO: is this necessary?
-        queueMicrotask(onError);
+        runTask(onError);
       } else {
-        queueMicrotask(onLoad);
+        runTask(onLoad);
       }
     }
 
@@ -253,7 +293,7 @@ export const Image = forwardRef(function Image(props: ImageProps, domRef: Forwar
     let img = (
       <img
         {...getFetchPriorityProp(fetchPriority)}
-        src={src || undefined}
+        src={typeof srcProp === 'string' && srcProp ? srcProp : undefined}
         alt={alt}
         crossOrigin={crossOrigin}
         decoding={decoding}
@@ -268,10 +308,28 @@ export const Image = forwardRef(function Image(props: ImageProps, domRef: Forwar
         className={imgStyles({isRevealed, isTransitioning})} />
     );
 
-    if (children) {
+    if (Array.isArray(srcProp)) {
       img = (
         <picture>
-          {children}
+          {srcProp.map((source, i) => {
+            let {colorScheme: sourceColorScheme, ...sourceProps} = source;
+            if (sourceColorScheme) {
+              if (!colorScheme || colorScheme === 'light dark') {
+                return (
+                  <source
+                    key={i}
+                    {...sourceProps}
+                    media={`${source.media ? `${source.media} and ` : ''}(prefers-color-scheme: ${sourceColorScheme})`} />
+                );
+              }
+
+              return sourceColorScheme === colorScheme
+                ? <source key={i} {...sourceProps} />
+                : null;
+            } else {
+              return <source key={i} {...sourceProps} />;
+            }
+          })}
           {img}
         </picture>
       );
@@ -287,7 +345,7 @@ export const Image = forwardRef(function Image(props: ImageProps, domRef: Forwar
         {!errorState && img}
       </div>
     );
-  }, [slot, hidden, domRef, UNSAFE_style, UNSAFE_className, styles, isAnimating, errorState, src, alt, crossOrigin, decoding, fetchPriority, loading, referrerPolicy, width, height, onLoad, onError, isRevealed, isTransitioning, children, itemProp]);
+  }, [slot, hidden, domRef, UNSAFE_style, UNSAFE_className, styles, isAnimating, errorState, alt, crossOrigin, decoding, fetchPriority, loading, referrerPolicy, width, height, onLoad, onError, isRevealed, isTransitioning, srcProp, itemProp, colorScheme]);
 });
 
 function getFetchPriorityProp(fetchPriority?: 'high' | 'low' | 'auto'): Record<string, string | undefined> {
diff --git a/packages/@react-spectrum/s2/src/Skeleton.tsx b/packages/@react-spectrum/s2/src/Skeleton.tsx
@@ -22,7 +22,7 @@ export function useLoadingAnimation(isAnimating: boolean): (element: HTMLElement
   let animationRef = useRef<Animation | null>(null);
   let reduceMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
   return useCallback((element: HTMLElement | null) => {
-    if (isAnimating && !animationRef.current && element && !reduceMotion) {
+    if (isAnimating && !animationRef.current && element && !reduceMotion && typeof element.animate === 'function') {
       // Use web animation API instead of CSS animations so that we can
       // synchronize it between all loading elements on the page (via startTime).
       animationRef.current = element.animate(
diff --git a/packages/@react-spectrum/s2/test/Image.test.tsx b/packages/@react-spectrum/s2/test/Image.test.tsx
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {Image, Provider} from '../src';
+import {render} from '@react-spectrum/test-utils-internal';
+
+describe('Image', () => {
+  it('should support conditional sources', async () => {
+    let {getByRole} = render(
+      <Image
+        alt="test"
+        src={[
+          {srcSet: 'foo.png', type: 'image/png', colorScheme: 'light'},
+          {srcSet: 'bar.png', colorScheme: 'dark', media: '(width >= 500px)'},
+          {srcSet: 'default.png'}
+        ]} />
+    );
+
+    let img = getByRole('img');
+    let picture = img.parentElement!;
+    expect(picture.tagName).toBe('PICTURE');
+    let sources = picture.querySelectorAll('source');
+
+    expect(sources).toHaveLength(3);
+    expect(sources[0]).toHaveAttribute('srcset', 'foo.png');
+    expect(sources[0]).toHaveAttribute('type', 'image/png');
+    expect(sources[0]).toHaveAttribute('media', '(prefers-color-scheme: light)');
+    expect(sources[1]).toHaveAttribute('srcset', 'bar.png');
+    expect(sources[1]).toHaveAttribute('media', '(width >= 500px) and (prefers-color-scheme: dark)');
+    expect(sources[2]).toHaveAttribute('srcset', 'default.png');
+  });
+
+  it('should support conditional sources with Provider colorScheme override', async () => {
+    let {getByRole} = render(
+      <Provider colorScheme="dark">
+        <Image
+          alt="test"
+          src={[
+            {srcSet: 'foo.png', type: 'image/png', colorScheme: 'light'},
+            {srcSet: 'bar.png', colorScheme: 'dark', media: '(width >= 500px)'},
+            {srcSet: 'default.png'}
+          ]} />
+      </Provider>
+    );
+
+    let img = getByRole('img');
+    let picture = img.parentElement!;
+    expect(picture.tagName).toBe('PICTURE');
+    let sources = picture.querySelectorAll('source');
+
+    expect(sources).toHaveLength(2);
+    expect(sources[0]).toHaveAttribute('srcset', 'bar.png');
+    expect(sources[0]).toHaveAttribute('media', '(width >= 500px)');
+    expect(sources[1]).toHaveAttribute('srcset', 'default.png');
+  });
+});
diff --git a/packages/dev/s2-docs/pages/s2/Image.mdx b/packages/dev/s2-docs/pages/s2/Image.mdx
@@ -21,6 +21,29 @@ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
   styles={style({width: 400, maxWidth: 'full', borderRadius: 'default'})} />
 ```
 
+## Conditional sources
+
+Set the `src` prop to an array of objects describing conditional images, e.g. media queries or image formats. These accept the same props as the &lt;[source](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source)&gt; HTML element, as well as `colorScheme` to conditionally render images based on the [Provider](Provider) color scheme.
+
+```tsx render type="s2" wide docs={docs.exports.Provider} links={docs.links} props={['colorScheme']}
+"use client";
+import {Image, Provider} from '@react-spectrum/s2';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
+
+<Provider/* PROPS */>
+  <Image
+    /*- begin highlight -*/
+    src={[
+      {colorScheme: 'light', srcSet: 'https://images.unsplash.com/photo-1722172118908-1a97c312ce8c?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D'},
+      {colorScheme: 'dark', srcSet: 'https://images.unsplash.com/photo-1722233987129-61dc344db8b6?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D'}
+    ]}
+    /*- end highlight -*/
+    alt="Conditional image"
+    styles={style({height: 300, maxWidth: 'full', borderRadius: 'default'})} />
+</Provider>
+```
+
+
 ## Error state
 
 Use `renderError` to display a custom error UI when an image fails to load.
diff --git a/packages/dev/s2-docs/src/ComponentCard.tsx b/packages/dev/s2-docs/src/ComponentCard.tsx
@@ -408,15 +408,15 @@ function ComponentIllustration({name, href}: IllustrationProps) {
 
   return (
     <Image
-      src={light}
+      src={[
+        {srcSet: light, colorScheme: 'light'},
+        {srcSet: dark, colorScheme: 'dark'}
+      ]}
       alt=""
       aria-hidden="true"
       width={960}
       height={600}
-      styles={illustrationStyles}>
-      <source srcSet={light} media="(prefers-color-scheme: light)" />
-      <source srcSet={dark} media="(prefers-color-scheme: dark)" />
-    </Image>
+      styles={illustrationStyles} />
   );
 }
 
@@ -443,16 +443,13 @@ export function ComponentCard({id, name, href, description, size, ...otherProps}
     preview = (
       <div className={illustrationContainer}>
         {/* Background gradient */}
-        <picture>
-          <source srcSet={BackgroundLight} media="(prefers-color-scheme: light)" />
-          <source srcSet={BackgroundDark} media="(prefers-color-scheme: dark)" />
-          <img
-            src={BackgroundLight}
-            alt=""
-            aria-hidden="true"
-            className={backgroundStyles}
-            loading="lazy" />
-        </picture>
+        <Image
+          alt=""
+          styles={backgroundStyles}
+          src={[
+            {srcSet: BackgroundLight, colorScheme: 'light'},
+            {srcSet: BackgroundDark, colorScheme: 'dark'}
+          ]} />
         <span className={releaseText}>{releaseVersion}</span>
       </div>
     );
diff --git a/packages/dev/s2-docs/src/ComponentCardClient.tsx b/packages/dev/s2-docs/src/ComponentCardClient.tsx
@@ -2,6 +2,7 @@
 import {Card, CardPreview, CardProps, Content, Text} from '@react-spectrum/s2';
 import {ReactNode, useEffect, useRef} from 'react';
 import {registerSpectrumLink} from './prefetch';
+import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
 
 interface ComponentCardProps extends Omit<CardProps, 'children'> {
   preview: ReactNode,
@@ -30,7 +31,7 @@ export function ComponentCardClient(props: ComponentCardProps) {
       <CardPreview>
         {preview}
       </CardPreview>
-      <Content>
+      <Content styles={style({alignContent: 'start'})}>
         <Text slot="title">{name}</Text>
         {description && <Text slot="description">{description}</Text>}
       </Content>
diff --git a/packages/dev/s2-docs/src/ExampleList.tsx b/packages/dev/s2-docs/src/ExampleList.tsx
@@ -99,12 +99,12 @@ export function ExampleImage({name, itemProp}: {name: string, itemProp?: string}
   let [light, dark] = img;
   return (
     <Image
-      src={light}
+      src={[
+        {srcSet: light, colorScheme: 'light'},
+        {srcSet: dark, colorScheme: 'dark'}
+      ]}
       alt=""
       itemProp={itemProp}
-      styles={image}>
-      <source srcSet={light} media="(prefers-color-scheme: light)" />
-      <source srcSet={dark} media="(prefers-color-scheme: dark)" />
-    </Image>
+      styles={image} />
   );
 }
diff --git a/packages/dev/s2-docs/src/VisualExampleClient.tsx b/packages/dev/s2-docs/src/VisualExampleClient.tsx
@@ -444,6 +444,9 @@ export function Control({name}: {name: string}) {
       if (name === 'placement' && control.value.elements.length === 22) {
         return <PlacementControl control={control} value={value} onChange={onChange} />;
       }
+      if (name === 'src') {
+        return <StringControl control={control} value={value} onChange={onChange} />;
+      }
       return <UnionControl control={control} value={value} onChange={onChange} />;
     case 'number':
       return <NumberControl control={control} value={value} onChange={onChange} />;
