Blur Image

Overview

Core Concept

The BlurImage component wraps Next.js Image to provide an enhanced loading experience with a shimmer animation and blur-to-clear transition. Built with class-variance-authority, it offers configurable intent, visuals, shape, and elevation variants for consistent styling across your application.

Key Features

• Shimmer animation — A subtle overlay sweeps across the placeholder while loading
• Blur-to-clear transition — Image starts blurred and scales down smoothly as it loads
• Default placeholder — Falls back to a neutral gray SVG placeholder
• Custom placeholder support — Provide your own blurDataURL for branded loading states
• Intent variants — Apply semantic color (primary, accent, secondary, success, info, warning, error, neutral) that controls background, text, and border colors
• Visual variants — Apply solid, dashed, dotted, or none border styling
• Shape variants — Control border radius with rounded, pill, or sharp
• Elevation variants — Control drop shadow: none, raised, floating
• SSR compatible — Works seamlessly with Next.js server-side rendering

Installation

Usage

Basic

<BlurImage src="/og-image.png" width={800} height={450} alt="Description" />

Composition

Combine with grid layouts or card components for gallery views:

<div className="grid grid-cols-2 gap-4">
  <BlurImage
    src="/photo-1.jpg"
    width={400}
    height={300}
    alt="Gallery image 1"
    intent="primary"
    visuals="dashed"
    shape="rounded"
  />
  <BlurImage
    src="/photo-2.jpg"
    width={400}
    height={300}
    alt="Gallery image 2"
    intent="primary"
    visuals="dashed"
    shape="rounded"
  />
</div>

Custom Placeholder

You can provide your own base64-encoded placeholder image:

<BlurImage
  src="/photo.jpg"
  width={800}
  height={450}
  alt="Photo"
  blurDataURL="data:image/png;base64,YOUR_BASE64_PLACEHOLDER..."
/>

API Reference

BlurImage

Accessibility

• Required alt attribute — Enforces descriptive alt text for screen readers
• Decorative images — Use alt="" for purely decorative images
• Reduced motion — Shimmer animation respects prefers-reduced-motion when styled appropriately

Notes

• The shimmer animation requires the shimmer keyframe in your CSS. Add this to your global styles:

@keyframes shimmer {
  0% {
    transform: translateX(-100%);
  }
  100% {
    transform: translateX(100%);
  }
}

• For production, consider a server-side preprocessing step to generate low-resolution data URLs for all remote assets.