@mad-core/react

React components for serving responsive, format-optimized images from a MAD (Media Assets Distributor) server.

Features

• <MadImage> — renders a <picture> element with automatic <source> generation for modern formats (avif, webp)
• useMadImage — hook for building memoized image URLs and srcSet strings
• buildMadUrl — low-level utility for constructing MAD image URLs with transforms
• Art direction — breakpoint-aware responsive sources via the sources prop
• Tree-shakeable — ESM-only, sideEffects: false
• TypeScript-first — full type definitions with JSDoc documentation
• Zero runtime dependencies — only react as a peer dependency

Installation

# npm
npm install @mad-core/react

# bun
bun add @mad-core/react

# pnpm
pnpm add @mad-core/react

# yarn
yarn add @mad-core/react

react 18 or 19 is required as a peer dependency.

Quick Start

import { MadImage } from "@mad-core/react";

function Hero() {
  return (
    <MadImage
      id="clx1abc2300001a2b3c4d5e6f"
      baseUrl="https://cdn.example.com"
      widths={[400, 800, 1200, 1600]}
      sizes="(max-width: 768px) 100vw, 50vw"
      alt="Hero banner"
      loading="lazy"
    />
  );
}

API Reference

<MadImage>

Renders a responsive <picture> element with optimized format sources.

| Prop | Type | Default | Description | |------|------|---------|-------------| | id | string | — | Required. MAD asset ID (CUID2) | | baseUrl | string | — | Required. MAD server base URL | | params | MadTransformParams | {} | Base transform params applied to all URLs | | widths | number[] | — | Responsive srcset widths | | sizes | string | — | HTML sizes attribute | | formats | Array<"avif" \| "webp" \| "jpg" \| "png"> | ["avif", "webp"] | Format priority list | | sources | MadSource[] | — | Art direction sources | | ...rest | ImgHTMLAttributes | — | Passed to the fallback <img> (alt, className, loading, etc.) |

Art direction example

<MadImage
  id="clx1abc2300001a2b3c4d5e6f"
  baseUrl="https://cdn.example.com"
  widths={[400, 800]}
  sizes="100vw"
  sources={[
    {
      media: "(min-width: 1024px)",
      params: { width: 1200, crop: "center" },
      widths: [1200, 1800, 2400],
      sizes: "80vw",
    },
  ]}
  alt="Responsive hero"
/>

useMadImage(params: MadUrlParams): UseMadImageResult

Hook that returns a memoized image URL and a srcSet builder function. Use this when you need full control over the rendered markup.

import { useMadImage } from "@mad-core/react";

function Avatar({ id }: { id: string }) {
  const { url, srcSet } = useMadImage({
    id,
    baseUrl: "https://cdn.example.com",
    width: 128,
    format: "webp",
  });

  return (
    <img
      src={url}
      srcSet={srcSet([128, 256, 384])}
      sizes="128px"
      alt="User avatar"
    />
  );
}

| Return field | Type | Description | |-------------|------|-------------| | url | string | Fully-qualified MAD image URL | | srcSet | (widths: number[]) => string | Generates a srcset string for the given widths |

buildMadUrl(params: MadUrlParams): string

Low-level utility to build a MAD image URL with optional transform query parameters.

import { buildMadUrl } from "@mad-core/react";

const url = buildMadUrl({
  id: "clx1abc2300001a2b3c4d5e6f",
  baseUrl: "https://cdn.example.com",
  width: 800,
  format: "webp",
  quality: 80,
});
// => "https://cdn.example.com/image/clx1abc2300001a2b3c4d5e6f?width=800&format=webp&q=80"

Types

MadTransformParams

| Field | Type | Description | |-------|------|-------------| | width | number | Target width in pixels | | height | number | Target height in pixels | | format | MadImageFormat | Output format | | quality | number | Output quality (1–100) | | crop | MadCrop | Crop strategy | | fit | MadFit | Resize fit mode |

MadUrlParams

Extends MadTransformParams with:

| Field | Type | Description | |-------|------|-------------| | id | string | MAD asset ID (CUID2) | | baseUrl | string | MAD server base URL |

MadSource

| Field | Type | Description | |-------|------|-------------| | media | string | CSS media query, e.g. "(min-width: 1024px)" | | params | MadTransformParams | Transform overrides for this breakpoint | | widths | number[] | srcset widths (overrides global) | | sizes | string | HTML sizes attribute for this source |

MadCrop

"auto" | "center" | "top" | "bottom" | "left" | "right" | [x, y, w, h]

MadFit

"cover" | "contain" | "fill" | "inside" | "outside"

MadImageFormat

"webp" | "avif" | "jpg" | "png" | "gif"

How It Works

<MadImage> renders a standard HTML <picture> element:

1. For each art direction source (sources prop), it generates <source> elements for every format in the formats list, each with the appropriate media, type, srcSet, and sizes attributes.
2. For global responsive widths (widths prop), it generates <source> elements for each format (no media attribute).
3. A fallback <img> element is rendered last with the base URL (no forced format), letting the browser negotiate the best option.

The browser evaluates sources top-to-bottom and picks the first match, giving you automatic format negotiation (avif > webp > fallback) with art-direction breakpoints.

License

MIT