feat(components)!: src an srcSet props for lazy loading

Author: johannschopplich

docs/integrations/nuxt.md

@@ -78,46 +78,50 @@ The `UnLazyImage` component accepts the following props:
 
 | Prop | Type | Description |
 | --- | --- | --- |
+| `src` | String | Image source URL to be lazy-loaded. |
+| `srcSet` | String | Image source set to be lazy-loaded. |
 | `autoSizes` | Boolean | A flag to indicate whether the sizes attribute should be automatically calculated. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
+| `placeholderSrc` | String | Optional image source URL for a custom placeholder image. Will be ignored if a BlurHash or ThumbHash is provided. |
 | `placeholderSize` | Number | The size of the longer edge (width or height) of the BlurHash image to be decoded, depending on the aspect ratio. This option only applies when the `blurhash` prop is used. |
 | `placeholderRatio` | Number | Aspect ratio (width / height) of the decoded BlurHash image. Only applies to SSR-decoded placeholder images from a BlurHash string. |
 | `lazyLoad` | Boolean | A flag to indicate whether the image should be lazy-loaded (default) or deferred until this prop is set to `true`. Note: Placeholder images from hashes will still be decoded. |
 | `ssr` | Boolean | Whether the ThumbHash or BlurHash should be decoded on the server. Overrides the global module configuration if set. |
 
 ## Examples
 
-::: info
-In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
-:::
-
 ```html
 <!-- Inlined placeholder image as data URI -->
 <UnLazyImage
-  src="data:image/svg+xml, ..."
-  data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+  placeholder-src="data:image/svg+xml, ..."
+  src-set="image-320w.jpg 320w, image-640w.jpg 640w"
   auto-sizes
 />
 ```
 
+::: tip
+In every `srcSet` example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
+:::
+
 ### BlurHash
 
 ::: code-group
   ```html [SSR-decoded BlurHash]
   <UnLazyImage
     :blurhash="blurhash"
     :blurhash-ratio="2"
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
     width="640"
     height="320"
   />
   ```
   ```html [Client-side decoded BlurHash]
   <UnLazyImage
-    :blurhash="blurhash"
     :ssr="false"
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    :blurhash="blurhash"
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
+    auto-sizes
     width="640"
     height="320"
   />
@@ -130,16 +134,18 @@ In each example, the `sizes` attribute is automatically calculated given the `au
   ```html [SSR-decoded ThumbHash]
   <UnLazyImage
     :thumbhash="thumbhash"
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
+    auto-sizes
     width="640"
     height="320"
   />
   ```
   ```html [Client-side decoded ThumbHash]
   <UnLazyImage
-    :thumbhash="thumbhash"
     :ssr="false"
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    :thumbhash="thumbhash"
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
+    auto-sizes
     width="640"
     height="320"
   />

docs/integrations/react.md

@@ -26,9 +26,9 @@ import { UnLazyImage } from '@unlazy/react'
 export default function MyComponent() {
   return (
     <UnLazyImage
+      blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      src="data:image/svg+xml, ..."
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
 }
@@ -46,43 +46,46 @@ The `UnLazyImage` component accepts the following props:
 
 | Prop | Type | Description |
 | --- | --- | --- |
+| `src` | String | Image source URL to be lazy-loaded. |
+| `srcSet` | String | Image source set to be lazy-loaded. |
 | `autoSizes` | Boolean | A flag to indicate whether the sizes attribute should be automatically calculated. |
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
+| `placeholderSrc` | String | Optional image source URL for a custom placeholder image. Will be ignored if a BlurHash or ThumbHash is provided. |
 | `placeholderSize` | Number | The size of the longer edge (width or height) of the BlurHash image to be decoded, depending on the aspect ratio. This option only applies when the `blurhash` prop is used. |
 
 ## Examples
 
-::: info
-In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
-:::
-
 ::: code-group
   ```tsx [BlurHash]
   return (
     <UnLazyImage
       blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
   ```
   ```tsx [ThumbHash]
   return (
     <UnLazyImage
       thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
   ```
   ```tsx [Inlined placeholder image]
   return (
     <UnLazyImage
+      placeholderSrc="data:image/svg+xml, ..."
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      src="data:image/svg+xml, ..."
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
   ```
 :::
+
+::: tip
+In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
+:::

docs/integrations/solid.md

@@ -26,9 +26,9 @@ import { UnLazyImage } from '@unlazy/solid'
 export default function MyComponent() {
   return (
     <UnLazyImage
+      blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      src="data:image/svg+xml, ..."
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
 }
@@ -46,43 +46,46 @@ The `UnLazyImage` component accepts the following props:
 
 | Prop | Type | Description |
 | --- | --- | --- |
+| `src` | String | Image source URL to be lazy-loaded. |
+| `srcSet` | String | Image source set to be lazy-loaded. |
 | `autoSizes` | Boolean | A flag to indicate whether the sizes attribute should be automatically calculated. |
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
+| `placeholderSrc` | String | Optional image source URL for a custom placeholder image. Will be ignored if a BlurHash or ThumbHash is provided. |
 | `placeholderSize` | Number | The size of the longer edge (width or height) of the BlurHash image to be decoded, depending on the aspect ratio. This option only applies when the `blurhash` prop is used. |
 
 ## Examples
 
-::: info
-In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
-:::
-
 ::: code-group
   ```tsx [BlurHash]
   return (
     <UnLazyImage
       blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
   ```
   ```tsx [ThumbHash]
   return (
     <UnLazyImage
       thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
   ```
   ```tsx [Inlined placeholder image]
   return (
     <UnLazyImage
+      placeholderSrc="data:image/svg+xml, ..."
+      srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
       autoSizes
-      src="data:image/svg+xml, ..."
-      data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
     />
   )
   ```
 :::
+
+::: tip
+In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
+:::

docs/integrations/svelte.md

@@ -26,9 +26,9 @@ Import the `UnLazyImage` component in your component file:
 </script>
 
 <UnLazyImage
+  blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+  srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
   autoSizes
-  src="data:image/svg+xml, ..."
-  data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
 />
 ```
 
@@ -44,37 +44,40 @@ The `UnLazyImage` component accepts the following props:
 
 | Prop | Type | Description |
 | --- | --- | --- |
+| `src` | String | Image source URL to be lazy-loaded. |
+| `srcSet` | String | Image source set to be lazy-loaded. |
 | `autoSizes` | Boolean | A flag to indicate whether the sizes attribute should be automatically calculated. |
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
+| `placeholderSrc` | String | Optional image source URL for a custom placeholder image. Will be ignored if a BlurHash or ThumbHash is provided. |
 | `placeholderSize` | Number | The size of the longer edge (width or height) of the BlurHash image to be decoded, depending on the aspect ratio. This option only applies when the `blurhash` prop is used. |
 
 ## Examples
 
-::: info
-In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
-:::
-
 ::: code-group
   ```svelte [BlurHash]
   <UnLazyImage
     blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+    srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
     autoSizes
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
   />
   ```
   ```svelte [ThumbHash]
   <UnLazyImage
     thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+    srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
     autoSizes
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
   />
   ```
   ```svelte [Inlined placeholder image]
   <UnLazyImage
+    placeholderSrc="data:image/svg+xml, ..."
+    srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
     autoSizes
-    src="data:image/svg+xml, ..."
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
   />
   ```
 :::
+
+::: tip
+In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
+:::

docs/integrations/vue.md

@@ -29,8 +29,8 @@ import { UnLazyImage } from '@unlazy/vue/components'
 
 <template>
   <UnLazyImage
-    src="data:image/svg+xml, ..."
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
     auto-sizes
   />
 </template>
@@ -64,34 +64,35 @@ The `UnLazyImage` component accepts the following props:
 | `autoSizes` | Boolean | A flag to indicate whether the sizes attribute should be automatically calculated. |
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
+| `placeholderSrc` | String | Optional image source URL for a custom placeholder image. Will be ignored if a BlurHash or ThumbHash is provided. |
 | `placeholderSize` | Number | The size of the longer edge (width or height) of the BlurHash image to be decoded, depending on the aspect ratio. This option only applies when the `blurhash` prop is used. |
 
 ## Examples
 
-::: info
-In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
-:::
-
 ::: code-group
-  ```vue [BlurHash]
+  ```html [BlurHash]
   <UnLazyImage
-    :blurhash="blurhash"
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
     auto-sizes
   />
   ```
-  ```vue [ThumbHash]
+  ```html [ThumbHash]
   <UnLazyImage
-    :thumbhash="thumbhash"
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
     auto-sizes
   />
   ```
-  ```vue [Inlined placeholder image]
+  ```html [Inlined placeholder image]
   <UnLazyImage
-    src="data:image/svg+xml, ..."
-    data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+    placeholder-src="data:image/svg+xml, ..."
+    src-set="image-320w.jpg 320w, image-640w.jpg 640w"
     auto-sizes
   />
   ```
 :::
+
+::: tip
+In each example, the `sizes` attribute is automatically calculated given the `auto-sizes` prop.
+:::

packages/react/playground/App.tsx

@@ -5,15 +5,14 @@ function App() {
     <>
       <UnLazyImage
         blurhash="LKO2:N%2Tw=w]~RBVZRi};RPxuwH"
+        srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
         autoSizes={true}
-        data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
         width="640"
         height="640"
       />
       <UnLazyImage
         thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
-        autoSizes={true}
-        data-srcset="image-320w.jpg 320w, image-640w.jpg 640w"
+        src="/images/sunrise-evan-wallace.jpg"
         width="480"
         height="640"
     />

packages/react/playground/public/images/sunrise-evan-wallace.jpg

@@ -6,6 +6,10 @@ import type { UnLazyLoadOptions } from 'unlazy'
 interface Props
   extends ImgHTMLAttributes<HTMLImageElement>,
   Pick<UnLazyLoadOptions, 'placeholderSize'> {
+  /** Image source URL to be lazy-loaded. */
+  src?: ImgHTMLAttributes<HTMLImageElement>['src']
+  /** Image source set to be lazy-loaded. */
+  srcSet?: ImgHTMLAttributes<HTMLImageElement>['srcSet']
   /**
    * A flag to indicate whether the sizes attribute should be automatically calculated.
    * @default false
@@ -15,12 +19,17 @@ interface Props
   blurhash?: string
   /** A ThumbHash string representing the blurry placeholder image. */
   thumbhash?: string
+  /** Optional image source URL for a custom placeholder image. Will be ignored if a BlurHash or ThumbHash is provided. */
+  placeholderSrc?: string
 }
 
 export function UnLazyImage({
+  src,
+  srcSet,
   autoSizes,
   blurhash,
   thumbhash,
+  placeholderSrc,
   placeholderSize,
   ...rest
 }: Props) {
@@ -37,11 +46,14 @@ export function UnLazyImage({
         cleanup()
       }
     }
-  }, [blurhash, thumbhash, placeholderSize])
+  }, [src, srcSet, autoSizes, blurhash, thumbhash, placeholderSrc, placeholderSize])
 
   return (
     <img
       ref={target}
+      src={placeholderSrc}
+      data-src={src}
+      data-srcset={srcSet}
       data-sizes={autoSizes ? 'auto' : undefined}
       loading="lazy"
       {...rest}