feat(components): immediate prop

Author: johannschopplich

docs/api/lazy-load.md

@@ -62,6 +62,18 @@ interface UnLazyLoadOptions {
    */
   placeholderSize?: number
 
+  /**
+   * Controls whether the image should be loaded immediately, or only when it
+   * enters the viewport.
+   *
+   * @remarks
+   * This option is intended primarily for internal usage in frontend framework
+   * components that need to control when single images should be loaded.
+   *
+   * @default false
+   */
+  immediate?: boolean
+
   /**
    * A callback function to run when an image is loaded.
    */

docs/integrations/nuxt.md

@@ -83,6 +83,7 @@ The `UnLazyImage` component accepts the following props:
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `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. |
+| `immediate` | A flag to indicate whether the image should be loaded immediately. |
 | `ssr` | Boolean | Whether the ThumbHash or BlurHash should be decoded on the server. Overrides the global module configuration if set. |
 
 ## Examples

docs/integrations/react.md

@@ -50,6 +50,7 @@ The `UnLazyImage` component accepts the following props:
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
 | `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. |
+| `immediate` | A flag to indicate whether the image should be loaded immediately. |
 
 ## Examples
 

docs/integrations/solid.md

@@ -50,6 +50,7 @@ The `UnLazyImage` component accepts the following props:
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
 | `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. |
+| `immediate` | A flag to indicate whether the image should be loaded immediately. |
 
 ## Examples
 

docs/integrations/vue.md

@@ -65,6 +65,7 @@ The `UnLazyImage` component accepts the following props:
 | `blurhash` | String | A BlurHash string representing the blurry placeholder image. |
 | `thumbhash` | String | A ThumbHash string representing the blurry placeholder image. |
 | `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. |
+| `immediate` | A flag to indicate whether the image should be loaded immediately. |
 
 ## Examples
 

packages/core/src/lazyLoad.ts

@@ -18,6 +18,7 @@ export function lazyLoad<T extends HTMLImageElement>(
     hash = true,
     hashType = 'blurhash',
     placeholderSize = DEFAULT_PLACEHOLDER_SIZE,
+    immediate = false,
     onImageLoad,
   }: UnLazyLoadOptions = {},
 ) {
@@ -27,6 +28,14 @@ export function lazyLoad<T extends HTMLImageElement>(
     // Calculate the image's `sizes` attribute if `data-sizes="auto"` is set
     updateSizesAttribute(image)
 
+    // Load the image right away if `immediate` is set to `true`
+    if (immediate) {
+      updatePictureSources(image)
+      updateImageSrcset(image)
+      updateImageSrc(image)
+      continue
+    }
+
     // Generate the blurry placeholder from a Blurhash or ThumbHash string if applicable
     if (__ENABLE_HASH_DECODING__ && hash) {
       const { blurhash, thumbhash } = image.dataset
@@ -50,7 +59,7 @@ export function lazyLoad<T extends HTMLImageElement>(
     if (isCrawler || !isLazyLoadingSupported) {
       updatePictureSources(image)
       updateImageSrcset(image)
-      onImageLoad?.(image)
+      updateImageSrc(image)
       continue
     }
 

packages/core/src/types.ts

@@ -35,6 +35,18 @@ export interface UnLazyLoadOptions {
    */
   placeholderSize?: number
 
+  /**
+   * Controls whether the image should be loaded immediately, or only when it
+   * enters the viewport.
+   *
+   * @remarks
+   * This option is intended primarily for internal usage in frontend framework
+   * components that need to control when single images should be loaded.
+   *
+   * @default false
+   */
+  immediate?: boolean
+
   /**
    * A callback function to run when an image is loaded.
    */

packages/nuxt/src/runtime/components/UnLazyImage.vue

@@ -8,7 +8,10 @@ import { onBeforeUnmount, onMounted, ref, useRuntimeConfig, watchEffect } from '
 const props = withDefaults(
   defineProps<{
     src?: ImgHTMLAttributes['src']
-    /** A flag to indicate whether the sizes attribute should be automatically calculated. */
+    /**
+     * A flag to indicate whether the sizes attribute should be automatically calculated.
+     * @default false
+     */
     autoSizes?: boolean
     /** A BlurHash string representing the blurry placeholder image. */
     blurhash?: string
@@ -18,6 +21,11 @@ const props = withDefaults(
     placeholderSize?: number
     /** Aspect ratio (width / height) of the decoded BlurHash image. Only applies to SSR-decoded placeholder images from a BlurHash string. */
     placeholderRatio?: number
+    /**
+     * A flag to indicate whether the image should be loaded immediately.
+     * @default false
+     */
+    immediate?: boolean
     /** Whether the ThumbHash or BlurHash should be decoded on the server. Overrides the global module configuration if set. */
     ssr?: boolean
   }>(),
@@ -28,6 +36,7 @@ const props = withDefaults(
     thumbhash: undefined,
     placeholderSize: undefined,
     placeholderRatio: undefined,
+    immediate: false,
     ssr: undefined,
   },
 )
@@ -60,6 +69,7 @@ onMounted(() => {
       hash: props.thumbhash || props.blurhash,
       hashType: props.thumbhash ? 'thumbhash' : 'blurhash',
       placeholderSize: props.placeholderSize || unlazy.placeholderSize,
+      immediate: props.immediate,
     })
   })
 })

packages/react/src/index.tsx

@@ -6,19 +6,28 @@ import type { UnLazyLoadOptions } from 'unlazy'
 interface Props
   extends ImgHTMLAttributes<HTMLImageElement>,
   Pick<UnLazyLoadOptions, 'placeholderSize'> {
-  /** A flag to indicate whether the sizes attribute should be automatically calculated. */
+  /**
+   * A flag to indicate whether the sizes attribute should be automatically calculated.
+   * @default false
+   */
   autoSizes?: boolean
   /** A BlurHash string representing the blurry placeholder image. */
   blurhash?: string
   /** A ThumbHash string representing the blurry placeholder image. */
   thumbhash?: string
+  /**
+   * A flag to indicate whether the image should be loaded immediately.
+   * @default false
+   */
+  immediate?: boolean
 }
 
 export function UnLazyImage({
   autoSizes,
   blurhash,
   thumbhash,
   placeholderSize,
+  immediate,
   ...rest
 }: Props) {
   const target = useRef<HTMLImageElement | null>(null)
@@ -29,12 +38,13 @@ export function UnLazyImage({
         hash: thumbhash || blurhash,
         hashType: thumbhash ? 'thumbhash' : 'blurhash',
         placeholderSize,
+        immediate,
       })
       return () => {
         cleanup()
       }
     }
-  }, [thumbhash, blurhash, placeholderSize])
+  }, [blurhash, thumbhash, placeholderSize, immediate])
 
   return (
     <img

packages/solid/src/index.tsx

@@ -8,12 +8,20 @@ import type { UnLazyLoadOptions } from 'unlazy'
 interface Props
   extends JSX.ImgHTMLAttributes<HTMLImageElement>,
   Pick<UnLazyLoadOptions, 'placeholderSize'> {
-  /** A flag to indicate whether the sizes attribute should be automatically calculated. */
+  /**
+   * A flag to indicate whether the sizes attribute should be automatically calculated.
+   * @default false
+   */
   autoSizes?: boolean
   /** A BlurHash string representing the blurry placeholder image. */
   blurhash?: string
   /** A ThumbHash string representing the blurry placeholder image. */
   thumbhash?: string
+  /**
+   * A flag to indicate whether the image should be loaded immediately.
+   * @default false
+   */
+  immediate?: boolean
 }
 
 export function UnLazyImage(props: Props) {
@@ -28,6 +36,7 @@ export function UnLazyImage(props: Props) {
         hash: props.thumbhash || props.blurhash,
         hashType: props.thumbhash ? 'thumbhash' : 'blurhash',
         placeholderSize: props.placeholderSize,
+        immediate: props.immediate,
       })
 
       onCleanup(() => {