Add experimental blurry placeholder to image component

packages/next/build/webpack-config.ts

@@ -1077,6 +1077,7 @@ export default async function getBaseWebpackConfig(
                 domains: config.images.domains,
               }
             : {}),
+          enableBlurryPlaceholder: config.experimental.enableBlurryPlaceholder,
         }),
         'process.env.__NEXT_ROUTER_BASEPATH': JSON.stringify(config.basePath),
         'process.env.__NEXT_HAS_REWRITES': JSON.stringify(hasRewrites),

packages/next/client/image.tsx

@@ -45,6 +45,8 @@ const VALID_LAYOUT_VALUES = [
 ] as const
 type LayoutValue = typeof VALID_LAYOUT_VALUES[number]
 
+type PlaceholderValue = 'blur' | 'empty'
+
 type ImgElementStyle = NonNullable<JSX.IntrinsicElements['img']['style']>
 
 export type ImageProps = Omit<
@@ -72,6 +74,13 @@ export type ImageProps = Omit<
         height: number | string
         layout?: Exclude<LayoutValue, 'fill'>
       }
+  ) &
+  (
+    | {
+        placeholder?: Exclude<PlaceholderValue, 'blur'>
+        blurDataURL?: never
+      }
+    | { placeholder: 'blur'; blurDataURL: string }
   )
 
 const {
@@ -80,6 +89,7 @@ const {
   loader: configLoader,
   path: configPath,
   domains: configDomains,
+  enableBlurryPlaceholder: configEnableBlurryPlaceholder,
 } =
   ((process.env.__NEXT_IMAGE_OPTS as any) as ImageConfig) || imageConfigDefault
 // sort smallest to largest
@@ -209,6 +219,24 @@ function defaultImageLoader(loaderProps: ImageLoaderProps) {
   )
 }
 
+function removePlaceholder(
+  element: HTMLImageElement | null,
+  placeholder: PlaceholderValue
+) {
+  const hasBlurryPlaceholder =
+    configEnableBlurryPlaceholder && placeholder === 'blur'
+  if (hasBlurryPlaceholder && element) {
+    if (element.complete) {
+      // If the real image fails to load, this will still remove the placeholder. This is the desired behavior for now, and will be revisited when error handling is worked on for the image component itself.
+      element.style.backgroundImage = 'none'
+    } else {
+      element.onload = () => {
+        element.style.backgroundImage = 'none'
+      }
+    }
+  }
+}
+
 export default function Image({
   src,
   sizes,
@@ -222,6 +250,8 @@ export default function Image({
   objectFit,
   objectPosition,
   loader = defaultImageLoader,
+  placeholder = 'empty',
+  blurDataURL,
   ...all
 }: ImageProps) {
   let rest: Partial<ImageProps> = all
@@ -239,6 +269,10 @@ export default function Image({
     delete rest['layout']
   }
 
+  if (!configEnableBlurryPlaceholder) {
+    placeholder = 'empty'
+  }
+
   if (process.env.NODE_ENV !== 'production') {
     if (!src) {
       throw new Error(
@@ -291,6 +325,14 @@ export default function Image({
   const heightInt = getInt(height)
   const qualityInt = getInt(quality)
 
+  const MIN_IMG_SIZE_FOR_PLACEHOLDER = 5000
+  const tooSmallForBlurryPlaceholder =
+    widthInt && heightInt && widthInt * heightInt < MIN_IMG_SIZE_FOR_PLACEHOLDER
+  const shouldShowBlurryPlaceholder =
+    configEnableBlurryPlaceholder &&
+    placeholder === 'blur' &&
+    !tooSmallForBlurryPlaceholder
+
   let wrapperStyle: JSX.IntrinsicElements['div']['style'] | undefined
   let sizerStyle: JSX.IntrinsicElements['div']['style'] | undefined
   let sizerSvg: string | undefined
@@ -316,6 +358,13 @@ export default function Image({
 
     objectFit,
     objectPosition,
+
+    ...(shouldShowBlurryPlaceholder
+      ? {
+          backgroundSize: 'cover',
+          backgroundImage: `url("${blurDataURL}")`,
+        }
+      : undefined),
   }
   if (
     typeof widthInt !== 'undefined' &&
@@ -462,7 +511,10 @@ export default function Image({
         {...imgAttributes}
         decoding="async"
         className={className}
-        ref={setRef}
+        ref={(element) => {
+          setRef(element)
+          removePlaceholder(element, placeholder)
+        }}
         style={imgStyle}
       />
       {priority ? (

packages/next/next-server/server/config-shared.ts

@@ -60,6 +60,7 @@ export type NextConfig = { [key: string]: any } & {
       skipValidation?: boolean
     }
     turboMode: boolean
+    enableBlurryPlaceholder: boolean
   }
 }
 
@@ -115,6 +116,7 @@ export const defaultConfig: NextConfig = {
     externalDir: false,
     serialWebpackBuild: false,
     turboMode: false,
+    enableBlurryPlaceholder: false,
   },
   future: {
     strictPostcssConfiguration: false,

packages/next/next-server/server/image-config.ts

@@ -13,6 +13,7 @@ export type ImageConfig = {
   loader: LoaderValue
   path: string
   domains?: string[]
+  enableBlurryPlaceholder: boolean
 }
 
 export const imageConfigDefault: ImageConfig = {
@@ -21,4 +22,5 @@ export const imageConfigDefault: ImageConfig = {
   path: '/_next/image',
   loader: 'default',
   domains: [],
+  enableBlurryPlaceholder: false,
 }

test/integration/image-component/default/pages/blurry-placeholder.js

@@ -0,0 +1,19 @@
+import React from 'react'
+import Image from 'next/image'
+
+export default function Page() {
+  return (
+    <div>
+      <p>Blurry Placeholder</p>
+      <Image
+        priority
+        id="blurry-placeholder"
+        src="/test.jpg"
+        width="400"
+        height="400"
+        placeholder="blur"
+        blurDataURL="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='400' viewBox='0 0 400 400'%3E%3Cfilter id='blur' filterUnits='userSpaceOnUse' color-interpolation-filters='sRGB'%3E%3CfeGaussianBlur stdDeviation='20' edgeMode='duplicate' /%3E%3CfeComponentTransfer%3E%3CfeFuncA type='discrete' tableValues='1 1' /%3E%3C/feComponentTransfer%3E%3C/filter%3E%3Cimage filter='url(%23blur)' href='data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMDAwMDAwQEBAQFBQUFBQcHBgYHBwsICQgJCAsRCwwLCwwLEQ8SDw4PEg8bFRMTFRsfGhkaHyYiIiYwLTA+PlT/wAALCAAKAAoBAREA/8QAMwABAQEAAAAAAAAAAAAAAAAAAAcJEAABAwUAAwAAAAAAAAAAAAAFAAYRAQMEEyEVMlH/2gAIAQEAAD8Az1bLPaxhiuk0QdeCOLDtHixN2dmd2bsc5FPX7VTREX//2Q==' x='0' y='0' height='100%25' width='100%25'/%3E%3C/svg%3E"
+      />
+    </div>
+  )
+}

test/integration/image-component/default/test/index.test.js

@@ -587,7 +587,10 @@ describe('Image Component Tests', () => {
         nextConfig,
         `
         module.exports = {
-          target: 'serverless'
+          target: 'serverless',
+          experimental: {
+            enableBlurryPlaceholder: true,
+          },
         }
       `
       )
@@ -600,6 +603,29 @@ describe('Image Component Tests', () => {
       await killApp(app)
     })
 
+    it('should have blurry placeholder when enabled', async () => {
+      const html = await renderViaHTTP(appPort, '/blurry-placeholder')
+      expect(html).toContain(
+        'background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='400' viewBox='0 0 400 400'%3E%3Cfilter id='blur' filterUnits='userSpaceOnUse' color-interpolation-filters='sRGB'%3E%3CfeGaussianBlur stdDeviation='20' edgeMode='duplicate' /%3E%3CfeComponentTransfer%3E%3CfeFuncA type='discrete' tableValues='1 1' /%3E%3C/feComponentTransfer%3E%3C/filter%3E%3Cimage filter='url(%23blur)' href='data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMDAwMDAwQEBAQFBQUFBQcHBgYHBwsICQgJCAsRCwwLCwwLEQ8SDw4PEg8bFRMTFRsfGhkaHyYiIiYwLTA+PlT/wAALCAAKAAoBAREA/8QAMwABAQEAAAAAAAAAAAAAAAAAAAcJEAABAwUAAwAAAAAAAAAAAAAFAAYRAQMEEyEVMlH/2gAIAQEAAD8Az1bLPaxhiuk0QdeCOLDtHixN2dmd2bsc5FPX7VTREX//2Q==' x='0' y='0' height='100%25' width='100%25'/%3E%3C/svg%3E")'
+      )
+    })
+
+    it('should remove blurry placeholder after image loads', async () => {
+      let browser
+      try {
+        browser = await webdriver(appPort, '/blurry-placeholder')
+        const id = 'blurry-placeholder'
+        const backgroundImage = await browser.eval(
+          `window.getComputedStyle(document.getElementById('${id}')).getPropertyValue('background-image')`
+        )
+        expect(backgroundImage).toBe('none')
+      } finally {
+        if (browser) {
+          await browser.close()
+        }
+      }
+    })
+
     runTests('serverless')
   })
 })