feat(image): add loading src to display loading state

apps/docs/content/components/image/customLoading.raw.jsx

@@ -0,0 +1,13 @@
+import {Image} from "@nextui-org/react";
+
+export default function App() {
+  return (
+    <Image
+      alt="NextUI Image with custom loading"
+      height={200}
+      loadingSrc="https://via.placeholder.com/300x200"
+      src="https://app.requestly.io/delay/1000/https://nextui-docs-v2.vercel.app/images/fruit-4.jpeg"
+      width={300}
+    />
+  );
+}

apps/docs/content/components/image/customLoading.ts

@@ -0,0 +1,9 @@
+import App from "./customLoading.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/docs/components/image.mdx

@@ -63,17 +63,26 @@ Image component has a built-in `skeleton` animation to indicate the image is loa
 
 > **Note**: The `URL` uses `https://app.requestly.io/delay` to simulate a slow network.
 
+### Custom Loading Image
+
+You can use the `loadingSrc` prop to display a loading image when the image provided in `src` is still loading.
+
+<CodeDemo displayMode="visible" title="Custom Loading" files={imageContent.customLoading} />
+
+> **Note**: The `URL` uses `https://app.requestly.io/delay` to simulate a slow network.
+
 ### Image with fallback
 
 You can use the `fallbackSrc` prop to display a fallback image when:
 
 - The `fallbackSrc` prop is provided.
-- The image provided in `src` is still loading.
 - The image provided in `src` fails to load.
 - The image provided in `src` is not found.
 
 <CodeDemo displayMode="visible" title="Image with fallback" files={imageContent.fallback} />
 
+> **Note**: You can have both `loadingSrc` and `fallbackSrc` props to cover multiple possibilities while loading and handling image errors.
+
 ### With Next.js Image
 
 Next.js provides an optimized [Image](https://nextjs.org/docs/app/api-reference/components/image) component,
@@ -152,11 +161,17 @@ you can use it with HeroUI `Image` component as well.
       type: "eager | lazy",
       description: "A loading strategy to use for the image.",
       default: "-"
+    },
+        {
+      attribute: "loadingSrc",
+      type: "string",
+      description: "The image source to display while the main image is loading. This helps provide visual feedback during the loading process.",
+      default: "-"
     },
     {
       attribute: "fallbackSrc",
       type: "string",
-      description: "The fallback image source.",
+      description: "The image source to display when the main image fails to load or encounters an error.",
       default: "-"
     },
     {

packages/components/image/src/image.tsx

@@ -13,6 +13,7 @@ const Image = forwardRef<"img", ImageProps>((props, ref) => {
     classNames,
     isBlurred,
     isZoomed,
+    loadingSrc,
     fallbackSrc,
     removeWrapper,
     disableSkeleton,
@@ -45,7 +46,7 @@ const Image = forwardRef<"img", ImageProps>((props, ref) => {
   }
 
   // when zoomed or showSkeleton, we need to wrap the image
-  if (isZoomed || !disableSkeleton || fallbackSrc) {
+  if (isZoomed || !disableSkeleton || loadingSrc || fallbackSrc) {
     return <div {...getWrapperProps()}> {isZoomed ? zoomed : img}</div>;
   }
 

packages/components/image/src/use-image.ts

@@ -21,9 +21,13 @@ interface Props extends HTMLHeroUIProps<"img"> {
    */
   isBlurred?: boolean;
   /**
-   * A fallback image.
+   * A fallback image when error encountered.
    */
   fallbackSrc?: React.ReactNode;
+  /**
+   * A loading image.
+   */
+  loadingSrc?: React.ReactNode;
   /**
    * Whether to disable the loading skeleton.
    * @default false
@@ -82,9 +86,10 @@ export function useImage(originalProps: UseImageProps) {
     classNames,
     loading,
     isBlurred,
+    loadingSrc,
     fallbackSrc,
     isLoading: isLoadingProp,
-    disableSkeleton = !!fallbackSrc,
+    disableSkeleton = !!loadingSrc,
     removeWrapper = false,
     onError,
     onLoad,
@@ -110,6 +115,7 @@ export function useImage(originalProps: UseImageProps) {
 
   const isImgLoaded = imageStatus === "loaded" && !isLoadingProp;
   const isLoading = imageStatus === "loading" || isLoadingProp;
+  const isFailed = imageStatus === "failed";
   const isZoomed = originalProps.isZoomed;
 
   const Component = as || "img";
@@ -131,8 +137,9 @@ export function useImage(originalProps: UseImageProps) {
     };
   }, [props?.width, props?.height]);
 
-  const showFallback = (!src || !isImgLoaded) && !!fallbackSrc;
-  const showSkeleton = isLoading && !disableSkeleton;
+  const showLoading = isLoading && !!loadingSrc;
+  const showFallback = (isFailed || !src || !isImgLoaded) && !!fallbackSrc;
+  const showSkeleton = isLoading && !disableSkeleton && !loadingSrc;
 
   const slots = useMemo(
     () =>
@@ -170,7 +177,11 @@ export function useImage(originalProps: UseImageProps) {
   };
 
   const getWrapperProps = useCallback<PropGetter>(() => {
-    const fallbackStyle = showFallback
+    const wrapperStyle = showLoading
+      ? {
+          backgroundImage: `url(${loadingSrc})`,
+        }
+      : showFallback && !showSkeleton
       ? {
           backgroundImage: `url(${fallbackSrc})`,
         }
@@ -179,11 +190,11 @@ export function useImage(originalProps: UseImageProps) {
     return {
       className: slots.wrapper({class: classNames?.wrapper}),
       style: {
-        ...fallbackStyle,
+        ...wrapperStyle,
         maxWidth: w,
       },
     };
-  }, [slots, showFallback, fallbackSrc, classNames?.wrapper, w]);
+  }, [slots, showLoading, showFallback, showSkeleton, fallbackSrc, classNames?.wrapper, w]);
 
   const getBlurredImgProps = useCallback<PropGetter>(() => {
     return {
@@ -200,6 +211,7 @@ export function useImage(originalProps: UseImageProps) {
     classNames,
     isBlurred,
     disableSkeleton,
+    loadingSrc,
     fallbackSrc,
     removeWrapper,
     isZoomed,

packages/components/image/stories/image.stories.tsx

@@ -114,6 +114,19 @@ export const Shadow = {
   },
 };
 
+export const Skeleton = {
+  render: LoadingTemplate,
+
+  args: {
+    ...defaultProps,
+    width: 300,
+    height: 450,
+    radius: "lg",
+    src: "https://app.requestly.io/delay/3000/https://images.unsplash.com/photo-1494790108377-be9c29b29330",
+    disableSkeleton: false,
+  },
+};
+
 export const AnimatedLoad = {
   args: {
     ...defaultProps,
@@ -123,27 +136,42 @@ export const AnimatedLoad = {
   },
 };
 
-export const Fallback = {
+export const CustomLoading = {
   render: LoadingTemplate,
 
   args: {
     ...defaultProps,
     width: 300,
     radius: "lg",
     src: "https://app.requestly.io/delay/3000/https://images.unsplash.com/photo-1539571696357-5a69c17a67c6",
-    fallbackSrc: "/images/placeholder_300x450.png",
+    loadingSrc: "/images/placeholder_300x450.png",
   },
 };
 
-export const Skeleton = {
+export const Fallback = {
   render: LoadingTemplate,
 
   args: {
     ...defaultProps,
     width: 300,
     height: 450,
     radius: "lg",
-    src: "https://app.requestly.io/delay/3000/https://images.unsplash.com/photo-1494790108377-be9c29b29330",
+    src: "wrong-src-address",
+    fallbackSrc: "/images/placeholder_300x450.png",
     disableSkeleton: false,
   },
 };
+
+export const CustomLoadingAndFallback = {
+  render: LoadingTemplate,
+
+  args: {
+    ...defaultProps,
+    width: 300,
+    height: 450,
+    radius: "lg",
+    src: "wrong-src-address",
+    loadingSrc: "/images/placeholder_300x450.png",
+    fallbackSrc: "/images/local-image-small.jpg",
+  },
+};