React SDK (@spronta/images-react)

npm · GitHub

Drop-in React component for Spronta images. Handles responsive srcset, blurhash LQIP placeholders, lazy loading, and fade-in transitions.

Install

npm install @spronta/images-react

Setup

Wrap your app with SprontaProvider:

import { Spronta } from "@spronta/images";
import { SprontaProvider } from "@spronta/images-react";

const client = new Spronta({
  baseUrl: "https://cdn.spronta.com",
  project: "my-project",
  defaults: { format: "auto", quality: "medium" },
});

export default function App({ children }) {
  return (
    <SprontaProvider client={client}>
      {children}
    </SprontaProvider>
  );
}

SprontaImage

import { SprontaImage } from "@spronta/images-react";

<SprontaImage
  path="hero.jpg"
  alt="Hero image"
  transforms={{ gravity: "auto", format: "webp" }}
  widths={[640, 1280, 1920]}
  blurhash="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
  width={1920}
  height={1080}
/>

Props

Prop	Type	Default	Description
path	string	—	Image path relative to project
alt	string	—	Alt text (required for a11y)
transforms	TransformOptions	—	CDN transform options
widths	number[]	[320,640,960,1280,1920]	Responsive breakpoints
sizes	string	"100vw"	HTML sizes attribute
blurhash	string	—	BlurHash for placeholder
width	number	—	Intrinsic width (for aspect ratio)
height	number	—	Intrinsic height (for aspect ratio)
loading	"lazy" \	"eager"	"lazy"	Loading strategy
className	string	—	CSS class on wrapper div
style	CSSProperties	—	Inline styles on wrapper div
onLoad	() => void	—	Callback when image loads

How it works

1. Generates src + srcset + sizes from the Spronta client
2. Renders a blurhash placeholder on a (32px, decoded client-side)
3. Shows the placeholder immediately with the average color as CSS fallback
4. Fades in the actual when it loads (0.3s opacity transition)
5. On SSR hydration, checks img.complete to skip the fade for cached images

useSpronta hook

Access the Spronta client anywhere in the component tree:

import { useSpronta } from "@spronta/images-react";

function MyComponent() {
  const spronta = useSpronta();
  const url = spronta.url("photo.jpg", { width: 400 });

  return <img src={url} alt="Photo" />;
}