usePlaceholder

A React hook for client components. It requires a Server Action to bridge the server-side image processing.

Signature

usePlaceholder(imageUrl: string | null | undefined, action: PlaceholderAction, options?: PlaceholderOptions): UsePlaceholderReturn

Returns

interface UsePlaceholderReturn {
  data: PlaceholderResult | null;  // { base64, color, metadata }
  isLoading: boolean;              // Loading state
  error: Error | null;             // Any error
  refetch: () => void;             // Manual refetch function
}

Example

'use client'
import Image from 'next/image'
import { usePlaceholder } from 'next-image-placeholder/react'
import { getPlaceholderAction } from './actions'

export function CustomCard({ src }: { src: string }) {
  const { data, isLoading } = usePlaceholder(src, getPlaceholderAction)

  if (isLoading || !data?.base64) return <Skeleton />

  return (
    <Image
        src={src}
        placeholder="blur"
        blurDataURL={data.base64}
        style={{ backgroundColor: data.color }}
        alt="Image"
        width={400}
        height={300}
    />
  )
}