@inoo-ch/payload-image-optimizer 1.4.6 → 1.4.7

package/AGENT_DOCS.md

@@ -219,7 +219,7 @@ Import from `@inoo-ch/payload-image-optimizer/client`:
 
 ### `ImageBox` Component
 
-Drop-in Next.js `<Image>` wrapper with automatic ThumbHash blur placeholders and focal point support.
+Drop-in Next.js `<Image>` wrapper with automatic ThumbHash blur placeholders, focal point support, and smooth fade-in transition.
 
 ```tsx
 import { ImageBox } from '@inoo-ch/payload-image-optimizer/client'
@@ -229,21 +229,55 @@ import { ImageBox } from '@inoo-ch/payload-image-optimizer/client'
 
 // With a plain URL string
 <ImageBox media="/images/fallback.jpg" alt="Fallback" width={800} height={600} />
+
+// Disable fade animation
+<ImageBox media={doc.image} alt="Photo" fade={false} />
+
+// Custom fade duration
+<ImageBox media={doc.image} alt="Photo" fadeDuration={300} />
 ```
 
 **Props:** Extends all Next.js `ImageProps` (except `src`), plus:
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `media` | `MediaResource \| string` | Payload media document or URL string |
-| `alt` | `string` | Alt text (overrides `media.alt`) |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `media` | `MediaResource \| string` | — | Payload media document or URL string |
+| `alt` | `string` | — | Alt text (overrides `media.alt`) |
+| `fade` | `boolean` | `true` | Enable smooth blur-to-sharp fade transition on load |
+| `fadeDuration` | `number` | `500` | Duration of the fade animation in milliseconds |
 
 Automatically applies:
 - ThumbHash blur placeholder (if available on the media resource)
+- Smooth blur-to-sharp fade transition on image load (disable with `fade={false}`)
 - Focal point positioning via `objectPosition` (using `focalX`/`focalY`)
 - Cache-busting via `updatedAt` query parameter
 - `objectFit: 'cover'` by default (overridable via `style`)
 
+### `FadeImage` Component
+
+Standalone Next.js `<Image>` wrapper with fade-in transition for use with `getImageOptimizerProps()`. Use this when you have a custom image component and want the fade effect without `ImageBox`.
+
+```tsx
+import { FadeImage, getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
+
+const optimizerProps = getImageOptimizerProps(resource)
+
+<FadeImage
+  src={resource.url}
+  alt=""
+  width={800}
+  height={600}
+  optimizerProps={optimizerProps}
+/>
+```
+
+**Props:** Extends all Next.js `ImageProps` (except `placeholder`, `blurDataURL`, `onLoad`), plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `optimizerProps` | `ImageOptimizerProps` | — | Props returned by `getImageOptimizerProps()` |
+| `fadeDuration` | `number` | `500` | Duration of the fade animation in milliseconds |
+
 ### `getImageOptimizerProps()` Utility
 
 For integrating with existing image components (e.g., the Payload website template's `ImageMedia`):
@@ -360,6 +394,7 @@ import type {
 
 import type {
   ImageBoxProps,
+  FadeImageProps,
   ImageOptimizerProps,    // return type of getImageOptimizerProps
 } from '@inoo-ch/payload-image-optimizer/client'
 ```

package/README.md

@@ -17,7 +17,8 @@ Built and maintained by [inoo.ch](https://inoo.ch) — a Swiss digital agency cr
 - **Bulk regeneration** — Re-process existing images from the admin UI with progress tracking
 - **Per-collection config** — Override formats, quality, and dimensions per collection
 - **Admin UI** — Status badges, file size savings, and blur previews in the sidebar
-- **ImageBox component** — Drop-in Next.js `<Image>` wrapper with automatic ThumbHash blur
+- **ImageBox component** — Drop-in Next.js `<Image>` wrapper with automatic ThumbHash blur and smooth fade-in
+- **FadeImage component** — Standalone fade-in image for custom setups using `getImageOptimizerProps()`
 
 ## Requirements
 
@@ -146,7 +147,7 @@ Payload CMS ships with [sharp](https://sharp.pixelplumbing.com/) built-in and ca
 | Blur hash placeholders | Requires custom hooks | ThumbHash generated automatically |
 | Optimization status & savings | Not available | Admin sidebar panel per image |
 | Bulk re-process existing images | Not available | One-click regeneration with progress tracking |
-| Next.js `<Image>` with blur placeholder | Manual wiring | Drop-in `<ImageBox>` component |
+| Next.js `<Image>` with blur placeholder | Manual wiring | Drop-in `<ImageBox>` / `<FadeImage>` components |
 | Per-collection format/quality overrides | N/A | Supported |
 
 ### CPU & Resource Impact
@@ -171,7 +172,7 @@ A **Regenerate Images** button appears in collection list views, allowing you to
 
 ## ImageBox Component
 
-The plugin exports an `ImageBox` component — a Next.js `<Image>` wrapper that automatically applies ThumbHash blur placeholders:
+The plugin exports an `ImageBox` component — a Next.js `<Image>` wrapper that automatically applies ThumbHash blur placeholders with a smooth blur-to-sharp fade transition:
 
 ```tsx
 import { ImageBox } from '@inoo-ch/payload-image-optimizer/client'
@@ -181,10 +182,17 @@ import { ImageBox } from '@inoo-ch/payload-image-optimizer/client'
 
 // Or use a plain URL string
 <ImageBox media="/images/photo.jpg" alt="Photo" width={800} height={600} />
+
+// Disable fade animation
+<ImageBox media={doc.image} alt="Photo" fade={false} />
+
+// Custom fade duration (default: 500ms)
+<ImageBox media={doc.image} alt="Photo" fadeDuration={300} />
 ```
 
 **Features:**
 - Automatic ThumbHash `blurDataURL` from the media document
+- Smooth blur-to-sharp fade transition on load (enabled by default)
 - Respects Payload focal point (`focalX` / `focalY`) for `objectPosition`
 - Lazy loading by default, with `priority` prop for above-the-fold images
 - Cache busting via `updatedAt` timestamp
@@ -254,7 +262,7 @@ Copy-paste this instruction to your AI coding agent to have it autonomously inte
 >
 > 1. Which upload collections should be optimized and with what settings
 > 2. Whether to use `replaceOriginal` or keep originals alongside variants
-> 3. Where to add `<ImageBox>` or `getImageOptimizerProps()` in the frontend for ThumbHash blur placeholders and focal point support
+> 3. Where to add `<ImageBox>`, `<FadeImage>`, or `getImageOptimizerProps()` in the frontend for ThumbHash blur placeholders with smooth fade-in and focal point support
 > 4. Whether any existing image rendering code should use the optimized variants
 >
 > Use the zero-config default (`collections: { <slug>: true }`) unless the project has specific requirements that call for custom settings.

package/dist/components/FadeImage.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import { type ImageProps } from 'next/image';
+import type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
+export interface FadeImageProps extends Omit<ImageProps, 'placeholder' | 'blurDataURL' | 'onLoad'> {
+    /** Props returned by `getImageOptimizerProps()`. */
+    optimizerProps: ImageOptimizerProps;
+    /** Duration of the fade animation in milliseconds. Defaults to `500`. */
+    fadeDuration?: number;
+}
+/**
+ * A Next.js `<Image>` wrapper that applies ThumbHash blur placeholders with a
+ * smooth blur-to-sharp fade transition on load.
+ *
+ * Use this when you call `getImageOptimizerProps()` manually instead of using `ImageBox`:
+ *
+ * ```tsx
+ * import { FadeImage, getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const optimizerProps = getImageOptimizerProps(resource)
+ * <FadeImage src={src} alt="" optimizerProps={optimizerProps} width={800} height={600} />
+ * ```
+ */
+export declare const FadeImage: React.FC<FadeImageProps>;

package/dist/components/FadeImage.js

@@ -0,0 +1,34 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useState } from 'react';
+import NextImage from 'next/image';
+/**
+ * A Next.js `<Image>` wrapper that applies ThumbHash blur placeholders with a
+ * smooth blur-to-sharp fade transition on load.
+ *
+ * Use this when you call `getImageOptimizerProps()` manually instead of using `ImageBox`:
+ *
+ * ```tsx
+ * import { FadeImage, getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const optimizerProps = getImageOptimizerProps(resource)
+ * <FadeImage src={src} alt="" optimizerProps={optimizerProps} width={800} height={600} />
+ * ```
+ */ export const FadeImage = ({ optimizerProps, style, fadeDuration = 500, ...props })=>{
+    const [loaded, setLoaded] = useState(false);
+    const { blurDataURL, style: optimizerStyle } = optimizerProps;
+    return /*#__PURE__*/ _jsx(NextImage, {
+        ...props,
+        placeholder: blurDataURL ? 'blur' : 'empty',
+        blurDataURL: blurDataURL,
+        style: {
+            ...optimizerStyle,
+            ...style,
+            filter: loaded ? 'blur(0px)' : 'blur(20px)',
+            transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined
+        },
+        onLoad: ()=>setLoaded(true)
+    });
+};
+
+//# sourceMappingURL=FadeImage.js.map

package/dist/components/FadeImage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/FadeImage.tsx"],"sourcesContent":["'use client'\n\nimport React, { useState } from 'react'\nimport NextImage, { type ImageProps } from 'next/image'\nimport type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\n\nexport interface FadeImageProps extends Omit<ImageProps, 'placeholder' | 'blurDataURL' | 'onLoad'> {\n  /** Props returned by `getImageOptimizerProps()`. */\n  optimizerProps: ImageOptimizerProps\n  /** Duration of the fade animation in milliseconds. Defaults to `500`. */\n  fadeDuration?: number\n}\n\n/**\n * A Next.js `<Image>` wrapper that applies ThumbHash blur placeholders with a\n * smooth blur-to-sharp fade transition on load.\n *\n * Use this when you call `getImageOptimizerProps()` manually instead of using `ImageBox`:\n *\n * ```tsx\n * import { FadeImage, getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'\n *\n * const optimizerProps = getImageOptimizerProps(resource)\n * <FadeImage src={src} alt=\"\" optimizerProps={optimizerProps} width={800} height={600} />\n * ```\n */\nexport const FadeImage: React.FC<FadeImageProps> = ({\n  optimizerProps,\n  style,\n  fadeDuration = 500,\n  ...props\n}) => {\n  const [loaded, setLoaded] = useState(false)\n\n  const { blurDataURL, style: optimizerStyle } = optimizerProps\n\n  return (\n    <NextImage\n      {...props}\n      placeholder={blurDataURL ? 'blur' : 'empty'}\n      blurDataURL={blurDataURL}\n      style={{\n        ...optimizerStyle,\n        ...style,\n        filter: loaded ? 'blur(0px)' : 'blur(20px)',\n        transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined,\n      }}\n      onLoad={() => setLoaded(true)}\n    />\n  )\n}\n"],"names":["React","useState","NextImage","FadeImage","optimizerProps","style","fadeDuration","props","loaded","setLoaded","blurDataURL","optimizerStyle","placeholder","filter","transition","undefined","onLoad"],"mappings":"AAAA;;AAEA,OAAOA,SAASC,QAAQ,QAAQ,QAAO;AACvC,OAAOC,eAAoC,aAAY;AAUvD;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC,YAAsC,CAAC,EAClDC,cAAc,EACdC,KAAK,EACLC,eAAe,GAAG,EAClB,GAAGC,OACJ;IACC,MAAM,CAACC,QAAQC,UAAU,GAAGR,SAAS;IAErC,MAAM,EAAES,WAAW,EAAEL,OAAOM,cAAc,EAAE,GAAGP;IAE/C,qBACE,KAACF;QACE,GAAGK,KAAK;QACTK,aAAaF,cAAc,SAAS;QACpCA,aAAaA;QACbL,OAAO;YACL,GAAGM,cAAc;YACjB,GAAGN,KAAK;YACRQ,QAAQL,SAAS,cAAc;YAC/BM,YAAYN,SAAS,CAAC,OAAO,EAAEF,aAAa,cAAc,CAAC,GAAGS;QAChE;QACAC,QAAQ,IAAMP,UAAU;;AAG9B,EAAC"}

package/dist/components/ImageBox.d.ts

@@ -4,5 +4,9 @@ import type { MediaResource } from '../types.js';
 export interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {
     media: MediaResource | string;
     alt?: string;
+    /** Enable smooth blur-to-sharp fade transition on load. Defaults to `true`. */
+    fade?: boolean;
+    /** Duration of the fade animation in milliseconds. Defaults to `500`. */
+    fadeDuration?: number;
 }
 export declare const ImageBox: React.FC<ImageBoxProps>;

package/dist/components/ImageBox.js

@@ -1,10 +1,15 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import React from 'react';
+import React, { useState } from 'react';
 import NextImage from 'next/image';
 import { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
-export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, loading: loadingFromProps, style: styleFromProps, ...props })=>{
+export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, loading: loadingFromProps, style: styleFromProps, fade = true, fadeDuration = 500, ...props })=>{
+    const [loaded, setLoaded] = useState(false);
     const loading = priority ? undefined : loadingFromProps ?? 'lazy';
+    const fadeStyle = fade ? {
+        filter: loaded ? 'blur(0px)' : 'blur(20px)',
+        transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined
+    } : undefined;
     if (typeof media === 'string') {
         return /*#__PURE__*/ _jsx(NextImage, {
             ...props,
@@ -16,10 +21,12 @@ export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, load
             style: {
                 objectFit: 'cover',
                 objectPosition: 'center',
+                ...fadeStyle,
                 ...styleFromProps
             },
             priority: priority,
-            loading: loading
+            loading: loading,
+            onLoad: fade ? ()=>setLoaded(true) : undefined
         });
     }
     const width = media.width ?? undefined;
@@ -39,12 +46,14 @@ export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, load
         style: {
             objectFit: 'cover',
             ...optimizerProps.style,
+            ...fadeStyle,
             ...styleFromProps
         },
         placeholder: optimizerProps.placeholder,
         blurDataURL: optimizerProps.blurDataURL,
         priority: priority,
-        loading: loading
+        loading: loading,
+        onLoad: fade ? ()=>setLoaded(true) : undefined
     });
 };
 

package/dist/components/ImageBox.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/ImageBox.tsx"],"sourcesContent":["'use client'\n\nimport React from 'react'\nimport NextImage, { type ImageProps } from 'next/image'\nimport type { MediaResource } from '../types.js'\nimport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\n\nexport interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {\n  media: MediaResource | string\n  alt?: string\n}\n\nexport const ImageBox: React.FC<ImageBoxProps> = ({\n  media,\n  alt: altFromProps,\n  fill,\n  sizes,\n  priority,\n  loading: loadingFromProps,\n  style: styleFromProps,\n  ...props\n}) => {\n  const loading = priority ? undefined : (loadingFromProps ?? 'lazy')\n\n  if (typeof media === 'string') {\n    return (\n      <NextImage\n        {...props}\n        src={media}\n        alt={altFromProps || ''}\n        quality={80}\n        fill={fill}\n        sizes={sizes}\n        style={{ objectFit: 'cover', objectPosition: 'center', ...styleFromProps }}\n        priority={priority}\n        loading={loading}\n      />\n    )\n  }\n\n  const width = media.width ?? undefined\n  const height = media.height ?? undefined\n  const alt = altFromProps || (media as any).alt || media.filename || ''\n  const src = media.url ? `${media.url}${media.updatedAt ? `?${media.updatedAt}` : ''}` : ''\n\n  const optimizerProps = getImageOptimizerProps(media)\n\n  return (\n    <NextImage\n      {...props}\n      src={src}\n      alt={alt}\n      quality={80}\n      fill={fill}\n      width={!fill ? width : undefined}\n      height={!fill ? height : undefined}\n      sizes={sizes}\n      style={{ objectFit: 'cover', ...optimizerProps.style, ...styleFromProps }}\n      placeholder={optimizerProps.placeholder}\n      blurDataURL={optimizerProps.blurDataURL}\n      priority={priority}\n      loading={loading}\n    />\n  )\n}\n"],"names":["React","NextImage","getImageOptimizerProps","ImageBox","media","alt","altFromProps","fill","sizes","priority","loading","loadingFromProps","style","styleFromProps","props","undefined","src","quality","objectFit","objectPosition","width","height","filename","url","updatedAt","optimizerProps","placeholder","blurDataURL"],"mappings":"AAAA;;AAEA,OAAOA,WAAW,QAAO;AACzB,OAAOC,eAAoC,aAAY;AAEvD,SAASC,sBAAsB,QAAQ,yCAAwC;AAO/E,OAAO,MAAMC,WAAoC,CAAC,EAChDC,KAAK,EACLC,KAAKC,YAAY,EACjBC,IAAI,EACJC,KAAK,EACLC,QAAQ,EACRC,SAASC,gBAAgB,EACzBC,OAAOC,cAAc,EACrB,GAAGC,OACJ;IACC,MAAMJ,UAAUD,WAAWM,YAAaJ,oBAAoB;IAE5D,IAAI,OAAOP,UAAU,UAAU;QAC7B,qBACE,KAACH;YACE,GAAGa,KAAK;YACTE,KAAKZ;YACLC,KAAKC,gBAAgB;YACrBW,SAAS;YACTV,MAAMA;YACNC,OAAOA;YACPI,OAAO;gBAAEM,WAAW;gBAASC,gBAAgB;gBAAU,GAAGN,cAAc;YAAC;YACzEJ,UAAUA;YACVC,SAASA;;IAGf;IAEA,MAAMU,QAAQhB,MAAMgB,KAAK,IAAIL;IAC7B,MAAMM,SAASjB,MAAMiB,MAAM,IAAIN;IAC/B,MAAMV,MAAMC,gBAAgB,AAACF,MAAcC,GAAG,IAAID,MAAMkB,QAAQ,IAAI;IACpE,MAAMN,MAAMZ,MAAMmB,GAAG,GAAG,GAAGnB,MAAMmB,GAAG,GAAGnB,MAAMoB,SAAS,GAAG,CAAC,CAAC,EAAEpB,MAAMoB,SAAS,EAAE,GAAG,IAAI,GAAG;IAExF,MAAMC,iBAAiBvB,uBAAuBE;IAE9C,qBACE,KAACH;QACE,GAAGa,KAAK;QACTE,KAAKA;QACLX,KAAKA;QACLY,SAAS;QACTV,MAAMA;QACNa,OAAO,CAACb,OAAOa,QAAQL;QACvBM,QAAQ,CAACd,OAAOc,SAASN;QACzBP,OAAOA;QACPI,OAAO;YAAEM,WAAW;YAAS,GAAGO,eAAeb,KAAK;YAAE,GAAGC,cAAc;QAAC;QACxEa,aAAaD,eAAeC,WAAW;QACvCC,aAAaF,eAAeE,WAAW;QACvClB,UAAUA;QACVC,SAASA;;AAGf,EAAC"}
+{"version":3,"sources":["../../src/components/ImageBox.tsx"],"sourcesContent":["'use client'\n\nimport React, { useState } from 'react'\nimport NextImage, { type ImageProps } from 'next/image'\nimport type { MediaResource } from '../types.js'\nimport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\n\nexport interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {\n  media: MediaResource | string\n  alt?: string\n  /** Enable smooth blur-to-sharp fade transition on load. Defaults to `true`. */\n  fade?: boolean\n  /** Duration of the fade animation in milliseconds. Defaults to `500`. */\n  fadeDuration?: number\n}\n\nexport const ImageBox: React.FC<ImageBoxProps> = ({\n  media,\n  alt: altFromProps,\n  fill,\n  sizes,\n  priority,\n  loading: loadingFromProps,\n  style: styleFromProps,\n  fade = true,\n  fadeDuration = 500,\n  ...props\n}) => {\n  const [loaded, setLoaded] = useState(false)\n  const loading = priority ? undefined : (loadingFromProps ?? 'lazy')\n\n  const fadeStyle = fade\n    ? {\n        filter: loaded ? 'blur(0px)' : 'blur(20px)',\n        transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined,\n      }\n    : undefined\n\n  if (typeof media === 'string') {\n    return (\n      <NextImage\n        {...props}\n        src={media}\n        alt={altFromProps || ''}\n        quality={80}\n        fill={fill}\n        sizes={sizes}\n        style={{ objectFit: 'cover', objectPosition: 'center', ...fadeStyle, ...styleFromProps }}\n        priority={priority}\n        loading={loading}\n        onLoad={fade ? () => setLoaded(true) : undefined}\n      />\n    )\n  }\n\n  const width = media.width ?? undefined\n  const height = media.height ?? undefined\n  const alt = altFromProps || (media as any).alt || media.filename || ''\n  const src = media.url ? `${media.url}${media.updatedAt ? `?${media.updatedAt}` : ''}` : ''\n\n  const optimizerProps = getImageOptimizerProps(media)\n\n  return (\n    <NextImage\n      {...props}\n      src={src}\n      alt={alt}\n      quality={80}\n      fill={fill}\n      width={!fill ? width : undefined}\n      height={!fill ? height : undefined}\n      sizes={sizes}\n      style={{ objectFit: 'cover', ...optimizerProps.style, ...fadeStyle, ...styleFromProps }}\n      placeholder={optimizerProps.placeholder}\n      blurDataURL={optimizerProps.blurDataURL}\n      priority={priority}\n      loading={loading}\n      onLoad={fade ? () => setLoaded(true) : undefined}\n    />\n  )\n}\n"],"names":["React","useState","NextImage","getImageOptimizerProps","ImageBox","media","alt","altFromProps","fill","sizes","priority","loading","loadingFromProps","style","styleFromProps","fade","fadeDuration","props","loaded","setLoaded","undefined","fadeStyle","filter","transition","src","quality","objectFit","objectPosition","onLoad","width","height","filename","url","updatedAt","optimizerProps","placeholder","blurDataURL"],"mappings":"AAAA;;AAEA,OAAOA,SAASC,QAAQ,QAAQ,QAAO;AACvC,OAAOC,eAAoC,aAAY;AAEvD,SAASC,sBAAsB,QAAQ,yCAAwC;AAW/E,OAAO,MAAMC,WAAoC,CAAC,EAChDC,KAAK,EACLC,KAAKC,YAAY,EACjBC,IAAI,EACJC,KAAK,EACLC,QAAQ,EACRC,SAASC,gBAAgB,EACzBC,OAAOC,cAAc,EACrBC,OAAO,IAAI,EACXC,eAAe,GAAG,EAClB,GAAGC,OACJ;IACC,MAAM,CAACC,QAAQC,UAAU,GAAGlB,SAAS;IACrC,MAAMU,UAAUD,WAAWU,YAAaR,oBAAoB;IAE5D,MAAMS,YAAYN,OACd;QACEO,QAAQJ,SAAS,cAAc;QAC/BK,YAAYL,SAAS,CAAC,OAAO,EAAEF,aAAa,cAAc,CAAC,GAAGI;IAChE,IACAA;IAEJ,IAAI,OAAOf,UAAU,UAAU;QAC7B,qBACE,KAACH;YACE,GAAGe,KAAK;YACTO,KAAKnB;YACLC,KAAKC,gBAAgB;YACrBkB,SAAS;YACTjB,MAAMA;YACNC,OAAOA;YACPI,OAAO;gBAAEa,WAAW;gBAASC,gBAAgB;gBAAU,GAAGN,SAAS;gBAAE,GAAGP,cAAc;YAAC;YACvFJ,UAAUA;YACVC,SAASA;YACTiB,QAAQb,OAAO,IAAMI,UAAU,QAAQC;;IAG7C;IAEA,MAAMS,QAAQxB,MAAMwB,KAAK,IAAIT;IAC7B,MAAMU,SAASzB,MAAMyB,MAAM,IAAIV;IAC/B,MAAMd,MAAMC,gBAAgB,AAACF,MAAcC,GAAG,IAAID,MAAM0B,QAAQ,IAAI;IACpE,MAAMP,MAAMnB,MAAM2B,GAAG,GAAG,GAAG3B,MAAM2B,GAAG,GAAG3B,MAAM4B,SAAS,GAAG,CAAC,CAAC,EAAE5B,MAAM4B,SAAS,EAAE,GAAG,IAAI,GAAG;IAExF,MAAMC,iBAAiB/B,uBAAuBE;IAE9C,qBACE,KAACH;QACE,GAAGe,KAAK;QACTO,KAAKA;QACLlB,KAAKA;QACLmB,SAAS;QACTjB,MAAMA;QACNqB,OAAO,CAACrB,OAAOqB,QAAQT;QACvBU,QAAQ,CAACtB,OAAOsB,SAASV;QACzBX,OAAOA;QACPI,OAAO;YAAEa,WAAW;YAAS,GAAGQ,eAAerB,KAAK;YAAE,GAAGQ,SAAS;YAAE,GAAGP,cAAc;QAAC;QACtFqB,aAAaD,eAAeC,WAAW;QACvCC,aAAaF,eAAeE,WAAW;QACvC1B,UAAUA;QACVC,SAASA;QACTiB,QAAQb,OAAO,IAAMI,UAAU,QAAQC;;AAG7C,EAAC"}

package/dist/exports/client.d.ts

@@ -1,6 +1,8 @@
 export { OptimizationStatus } from '../components/OptimizationStatus.js';
 export { ImageBox } from '../components/ImageBox.js';
 export type { ImageBoxProps } from '../components/ImageBox.js';
+export { FadeImage } from '../components/FadeImage.js';
+export type { FadeImageProps } from '../components/FadeImage.js';
 export { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
 export type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
 export { RegenerationButton } from '../components/RegenerationButton.js';

package/dist/exports/client.js

@@ -1,5 +1,6 @@
 export { OptimizationStatus } from '../components/OptimizationStatus.js';
 export { ImageBox } from '../components/ImageBox.js';
+export { FadeImage } from '../components/FadeImage.js';
 export { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
 export { RegenerationButton } from '../components/RegenerationButton.js';
 

package/dist/exports/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/exports/client.ts"],"sourcesContent":["export { OptimizationStatus } from '../components/OptimizationStatus.js'\nexport { ImageBox } from '../components/ImageBox.js'\nexport type { ImageBoxProps } from '../components/ImageBox.js'\nexport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport { RegenerationButton } from '../components/RegenerationButton.js'\n"],"names":["OptimizationStatus","ImageBox","getImageOptimizerProps","RegenerationButton"],"mappings":"AAAA,SAASA,kBAAkB,QAAQ,sCAAqC;AACxE,SAASC,QAAQ,QAAQ,4BAA2B;AAEpD,SAASC,sBAAsB,QAAQ,yCAAwC;AAE/E,SAASC,kBAAkB,QAAQ,sCAAqC"}
+{"version":3,"sources":["../../src/exports/client.ts"],"sourcesContent":["export { OptimizationStatus } from '../components/OptimizationStatus.js'\nexport { ImageBox } from '../components/ImageBox.js'\nexport type { ImageBoxProps } from '../components/ImageBox.js'\nexport { FadeImage } from '../components/FadeImage.js'\nexport type { FadeImageProps } from '../components/FadeImage.js'\nexport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport { RegenerationButton } from '../components/RegenerationButton.js'\n"],"names":["OptimizationStatus","ImageBox","FadeImage","getImageOptimizerProps","RegenerationButton"],"mappings":"AAAA,SAASA,kBAAkB,QAAQ,sCAAqC;AACxE,SAASC,QAAQ,QAAQ,4BAA2B;AAEpD,SAASC,SAAS,QAAQ,6BAA4B;AAEtD,SAASC,sBAAsB,QAAQ,yCAAwC;AAE/E,SAASC,kBAAkB,QAAQ,sCAAqC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inoo-ch/payload-image-optimizer",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Payload CMS plugin for automatic image optimization — WebP/AVIF conversion, resize, EXIF strip, ThumbHash placeholders, and bulk regeneration",
   "license": "MIT",
   "keywords": [

package/src/components/FadeImage.tsx

@@ -0,0 +1,51 @@
+'use client'
+
+import React, { useState } from 'react'
+import NextImage, { type ImageProps } from 'next/image'
+import type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
+
+export interface FadeImageProps extends Omit<ImageProps, 'placeholder' | 'blurDataURL' | 'onLoad'> {
+  /** Props returned by `getImageOptimizerProps()`. */
+  optimizerProps: ImageOptimizerProps
+  /** Duration of the fade animation in milliseconds. Defaults to `500`. */
+  fadeDuration?: number
+}
+
+/**
+ * A Next.js `<Image>` wrapper that applies ThumbHash blur placeholders with a
+ * smooth blur-to-sharp fade transition on load.
+ *
+ * Use this when you call `getImageOptimizerProps()` manually instead of using `ImageBox`:
+ *
+ * ```tsx
+ * import { FadeImage, getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const optimizerProps = getImageOptimizerProps(resource)
+ * <FadeImage src={src} alt="" optimizerProps={optimizerProps} width={800} height={600} />
+ * ```
+ */
+export const FadeImage: React.FC<FadeImageProps> = ({
+  optimizerProps,
+  style,
+  fadeDuration = 500,
+  ...props
+}) => {
+  const [loaded, setLoaded] = useState(false)
+
+  const { blurDataURL, style: optimizerStyle } = optimizerProps
+
+  return (
+    <NextImage
+      {...props}
+      placeholder={blurDataURL ? 'blur' : 'empty'}
+      blurDataURL={blurDataURL}
+      style={{
+        ...optimizerStyle,
+        ...style,
+        filter: loaded ? 'blur(0px)' : 'blur(20px)',
+        transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined,
+      }}
+      onLoad={() => setLoaded(true)}
+    />
+  )
+}

package/src/components/ImageBox.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import React from 'react'
+import React, { useState } from 'react'
 import NextImage, { type ImageProps } from 'next/image'
 import type { MediaResource } from '../types.js'
 import { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
@@ -8,6 +8,10 @@ import { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
 export interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {
   media: MediaResource | string
   alt?: string
+  /** Enable smooth blur-to-sharp fade transition on load. Defaults to `true`. */
+  fade?: boolean
+  /** Duration of the fade animation in milliseconds. Defaults to `500`. */
+  fadeDuration?: number
 }
 
 export const ImageBox: React.FC<ImageBoxProps> = ({
@@ -18,10 +22,20 @@ export const ImageBox: React.FC<ImageBoxProps> = ({
   priority,
   loading: loadingFromProps,
   style: styleFromProps,
+  fade = true,
+  fadeDuration = 500,
   ...props
 }) => {
+  const [loaded, setLoaded] = useState(false)
   const loading = priority ? undefined : (loadingFromProps ?? 'lazy')
 
+  const fadeStyle = fade
+    ? {
+        filter: loaded ? 'blur(0px)' : 'blur(20px)',
+        transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined,
+      }
+    : undefined
+
   if (typeof media === 'string') {
     return (
       <NextImage
@@ -31,9 +45,10 @@ export const ImageBox: React.FC<ImageBoxProps> = ({
         quality={80}
         fill={fill}
         sizes={sizes}
-        style={{ objectFit: 'cover', objectPosition: 'center', ...styleFromProps }}
+        style={{ objectFit: 'cover', objectPosition: 'center', ...fadeStyle, ...styleFromProps }}
         priority={priority}
         loading={loading}
+        onLoad={fade ? () => setLoaded(true) : undefined}
       />
     )
   }
@@ -55,11 +70,12 @@ export const ImageBox: React.FC<ImageBoxProps> = ({
       width={!fill ? width : undefined}
       height={!fill ? height : undefined}
       sizes={sizes}
-      style={{ objectFit: 'cover', ...optimizerProps.style, ...styleFromProps }}
+      style={{ objectFit: 'cover', ...optimizerProps.style, ...fadeStyle, ...styleFromProps }}
       placeholder={optimizerProps.placeholder}
       blurDataURL={optimizerProps.blurDataURL}
       priority={priority}
       loading={loading}
+      onLoad={fade ? () => setLoaded(true) : undefined}
     />
   )
 }

package/src/exports/client.ts

@@ -1,6 +1,8 @@
 export { OptimizationStatus } from '../components/OptimizationStatus.js'
 export { ImageBox } from '../components/ImageBox.js'
 export type { ImageBoxProps } from '../components/ImageBox.js'
+export { FadeImage } from '../components/FadeImage.js'
+export type { FadeImageProps } from '../components/FadeImage.js'
 export { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
 export type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
 export { RegenerationButton } from '../components/RegenerationButton.js'