!Page Speed React Image Component

---

⚡ @page-speed/img

Performance-optimized React Image component

Drop-in Image implementation of web.dev best practices with zero configuration. Also a great alternative to next/image for non-Next.js projects that still need the automated image optimization tools that the Next Image component provides.


Documentation · Quick Start · Hooks · Examples · Contributing

---

Documentation

@page-speed/img is a React-first, OptixFlow-enabled image component that ships Lighthouse-friendly markup by default. It uses useOptimizedImage from @page-speed/hooks to compute pixel-perfect src, DPR-aware srcset, and sizes on the client. Tree shaking keeps the bundle lean—only the media hook is pulled in.

$3

``bash
pnpm add @page-speed/img
`

Peer deps: react and react-dom (17+). For OptixFlow optimization, supply an API key.

$3

`tsx
import { Img, setDefaultOptixFlowConfig } from "@page-speed/img";

// Optional: set once at app start
setDefaultOptixFlowConfig({ apiKey: process.env.NEXT_PUBLIC_OPTIX_API_KEY!, compressionLevel: 80 });

export function HeroImage() {
return (
src="https://images.example.com/hero.jpg"
alt="Hero"
width={1280}
height={720}
// Per-image override (optional)
optixFlowConfig={{ renderedFileType: "jpeg", objectFit: "cover" }}
/>
);
}
`

What you get:
- Pixel-perfect primary src sized to the rendered element (Lighthouse “Properly size images” pass).
- DPR-aware srcset (1x/2x) for AVIF/WebP/JPEG.
- Lazy loading with IntersectionObserver; set eager for above-the-fold.
- Optional OptixFlow compression/format selection with a single prop.

$3

- src (string, required): Image URL.
- alt, title, standard attributes.
- width, height: Set for CLS prevention; used as hints for sizing. Actual rendered size is measured to generate the pixel-perfect URL.
- loading, decoding: Defaults lazy / async. Set eager to force above-the-fold fetch.
- sizes: Override the auto-generated sizes from useOptimizedImage.
- intersectionMargin, intersectionThreshold: Tweak lazy-load observer.
- optixFlowConfig: { apiKey: string; compressionLevel?: number; renderedFileType?: 'avif' | 'webp' | 'jpeg' | 'png'; objectFit?: 'cover' | 'contain' | 'fill'; }.

$3

- Programmatic: setDefaultOptixFlowConfig({ apiKey: '...' }) once during app init.
- Browser global (UMD/inline):

`html

`

window.OpensiteImgDefaults and window.PAGE_SPEED_IMG_DEFAULTS are also honored for backward compatibility.

$3

`html






`

$3

- The component is client-only ("use client"). For SSR apps, render it in client components/entry points.
- Safe in non-browser contexts: guards exist for window/IntersectionObserver.

$3

@page-speed/img only imports useOptimizedImage from @page-speed/hooks, keeping bundles small. Both ESM and CJS builds are emitted; UMD is externalized to React/ReactDOM.

$3

`bash
pnpm test
`

$3

- Add storybook examples for common layouts (hero, gallery, card).

---

Contributing

PRs welcome. Please run pnpm test` before submitting.