feat: image transitions

README.md

@@ -16,6 +16,7 @@ Universal lazy loading library leveraging native browser APIs. It is intended to
 - 🔍 **SEO-friendly**: Detects search engine bots and preloads all images
 - 🎟 **`<picture>`**: Supports multiple image tags
 - 🏎 **Auto-initialize**: Usable without a build step
+- 🎉 **Fade Transitions**: Optionally fade (in ms) between BlurHash and ThumbHash to your loaded image with `:transition="500"`
 
 ## Setup
 

docs/guide/usage.md

@@ -106,7 +106,19 @@ const coolImage = document.querySelector('.image-to-load-first')
 // Trigger the load before the image enters the viewport
 loadImage(coolImage)
 ```
-
 ::: tip
 Keep in mind that manually loading images might negatively affect the perceived performance, as it will force the full-quality image to load immediately, even if it is not visible on the viewport.
 :::
+
+## Image Transitions
+
+You can easily add a fade transition between your BlurHash/ThumbHash and loaded image using the `:transition` prop. The transition uses canvas for smooth cross-fading.
+
+Note: Transition time is measured in milliseconds. Values between 300-1000ms typically work best.
+
+```ts
+<UnLazyImage
+  :thumbhash="thumbhash"
+  :transition="500"
+  src="data:image/svg+xml, ..."
+/>

docs/integrations/nuxt.md

@@ -92,6 +92,7 @@ The `UnLazyImage` component accepts the following props:
 | `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. |
+| `:transition` | Number | Time in MS for BlurHash/ThumbHash to transition to lazy loaded image. |
 | `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. |
 | `preload` | Boolean | A flag to indicate whether the image should be preloaded, even if it is not in the viewport yet. |
 | `ssr` | Boolean | Whether the ThumbHash or BlurHash should be decoded on the server. Overrides the global module configuration if set. |
@@ -207,3 +208,18 @@ Useful if the `UnLazyImage` is part of e.g. a slider, and you want to preload th
     preload
   />
 </template>
+```
+
+### Transition
+
+Easily add a fade transition.
+
+```vue
+<template>
+  <UnLazyImage
+    src="imageSrc"
+    :thumbhash="thumbhash"
+    :transition="500"
+  />
+</template>
+```

docs/integrations/react.md

@@ -53,6 +53,7 @@ The `UnLazyImage` component accepts the following props:
 | `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. |
+| `transition` | Number | Time in MS for BlurHash/ThumbHash to transition to lazy loaded image. |
 
 ## Examples
 
@@ -84,6 +85,15 @@ The `UnLazyImage` component accepts the following props:
     />
   )
   ```
+  ```tsx [Transition]
+  return (
+    <UnLazyImage
+      thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+      transition={500}
+    />
+  )
+  ```
+
 :::
 
 ::: tip

docs/integrations/solid.md

@@ -53,6 +53,7 @@ The `UnLazyImage` component accepts the following props:
 | `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. |
+| `transition` | Number | Time in MS for BlurHash/ThumbHash to transition to lazy loaded image. |
 
 ## Examples
 
@@ -84,6 +85,14 @@ The `UnLazyImage` component accepts the following props:
     />
   )
   ```
+  ```tsx [Transition]
+  return (
+    <UnLazyImage
+      thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+      transition={500}
+    />
+  )
+  ```
 :::
 
 ::: tip

docs/integrations/svelte.md

@@ -55,6 +55,7 @@ The `UnLazyImage` component accepts the following props:
 | `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. |
+| `transition` | Number | Time in MS for BlurHash/ThumbHash to transition to lazy loaded image. |
 
 ## Examples
 
@@ -80,6 +81,12 @@ The `UnLazyImage` component accepts the following props:
     autoSizes
   />
   ```
+  ```svelte [Transition]
+  <UnLazyImage
+    thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+    transition={500}
+  />
+  ```
 :::
 
 ::: tip

docs/integrations/vue.md

@@ -66,6 +66,7 @@ The `UnLazyImage` component accepts the following props:
 | `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. |
+| `:transition` | Number | Time in MS for BlurHash/ThumbHash to transition to lazy loaded image. |
 | `preload` | Boolean | A flag to indicate whether the image should be preloaded, even if it is not in the viewport yet. |
 
 ### Emitted Events
@@ -98,6 +99,13 @@ The `UnLazyImage` component accepts the following props:
     auto-sizes
   />
   ```
+  ```html [Transition]
+  <UnLazyImage
+    placeholder-src="data:image/svg+xml, ..."
+    thumbhash="1QcSHQRnh493V4dIh4eXh1h4kJUI"
+    :transition="500"
+  />
+  ```
 :::
 
 ::: tip