@pixelfiddler/react

React components for PixelFiddler image transformations with automatic responsive image support.

Installation

npm install @pixelfiddler/react
# or
pnpm add @pixelfiddler/react
# or
yarn add @pixelfiddler/react

Note: This package requires react >= 18.2.0 as a peer dependency.

Quick Start

import { PixelFiddlerImage } from '@pixelfiddler/react';

function App() {
  return (
    <PixelFiddlerImage
      src="https://example.com/photo.jpg"
      alt="A beautiful photo"
      width={800}
      transformations={{ format: 'WEBP', quality: 80 }}
    />
  );
}

Components

PixelFiddlerImage

A drop-in replacement for the <img> element that automatically generates optimized srcSet for responsive images.

import { PixelFiddlerImage } from '@pixelfiddler/react';

// Fixed-width image with DPR support (x descriptors)
<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Profile photo"
  width={400}
/>
// Generates: srcset="...?w=640 1x, ...?w=828 2x"

// Fluid/responsive image (w descriptors)
<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Hero image"
  sizes="(max-width: 768px) 100vw, 50vw"
/>
// Generates: srcset="...?w=320 320w, ...?w=640 640w, ..."

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | required | URL of the image (relative or absolute). Relative paths are attached to baseUrl | | alt | string | - | Alt text (required for accessibility) | | baseUrl | string | - | Base URL endpoint from PixelFiddler Dashboard. Can be set via PixelFiddlerProvider or passed directly | | width | number \| string | - | Display width in CSS pixels. Generates DPR descriptors (1x, 2x) | | sizes | string | - | Sizes attribute for responsive images. Generates width descriptors (w). Required if no fixed width is provided | | transformations | TransformationOptions | - | Image transformation options | | responsive | boolean | true | Enable automatic srcSet generation. Ignored if transformations.width is set | | deviceBreakpoints | number[] | - | Custom device breakpoints for responsive srcset | | imageBreakpoints | number[] | - | Custom image breakpoints for smaller images |

All standard <img> attributes (className, loading, decoding, etc.) are also supported.

PixelFiddlerProvider

A context provider for sharing configuration across all PixelFiddlerImage components.

import { PixelFiddlerProvider, PixelFiddlerImage } from '@pixelfiddler/react';

function App() {
  return (
    <PixelFiddlerProvider config={{ baseUrl: 'https://cdn.example.com' }}>
      <PixelFiddlerImage src="/photos/hero.jpg" alt="Hero" sizes="100vw" />
      <PixelFiddlerImage src="/photos/thumb.jpg" alt="Thumbnail" width={200} />
    </PixelFiddlerProvider>
  );
}

Props

| Prop | Type | Description | |------|------|-------------| | config | PixelFiddlerConfig | Configuration object with baseUrl and optional maxDpr | | children | ReactNode | Child components |

Usage Examples

Basic Transformations

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Transformed image"
  responsive={false}
  transformations={{
    width: 800,
    height: 600,
    format: 'WEBP',
    quality: 85,
  }}
/>

Responsive Image with Fixed Display Width

When you know the exact display size, use width to generate DPR variants:

<PixelFiddlerImage
  src="https://example.com/avatar.jpg"
  alt="User avatar"
  width={150}
  transformations={{ format: 'WEBP' }}
/>
// Output:
// src="...?w=384&f=WEBP"
// srcset="...?w=384&f=WEBP 1x, ...?w=640&f=WEBP 2x"

Responsive Image with Fluid Layout

For images that scale with the viewport, use sizes:

<PixelFiddlerImage
  src="https://example.com/hero.jpg"
  alt="Hero banner"
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 800px"
  transformations={{ format: 'WEBP', quality: 80 }}
/>
// Generates srcset with width descriptors (320w, 640w, 768w, etc.)

Custom Breakpoints

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Custom breakpoints"
  sizes="100vw"
  deviceBreakpoints={[480, 768, 1024, 1440, 1920]}
  imageBreakpoints={[]}
/>

Disable Responsive Behavior

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Non-responsive"
  responsive={false}
  transformations={{ width: 400, format: 'WEBP' }}
/>
// Output: just src, no srcset

With Standard Image Attributes

<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Lazy loaded image"
  width={600}
  className="rounded-lg shadow-md"
  loading="lazy"
  decoding="async"
/>

Responsive Strategy

The component automatically chooses the appropriate srcSet strategy:

| Input | Strategy | Descriptor | Use Case | |-------|----------|------------|----------| | width only | Fixed-size | x (1x, 2x) | Known display size, needs high-DPI support | | sizes only | Fluid | w (640w, 1200w) | Image size varies with viewport | | Neither | Fluid | w | Full-width responsive image (defaults to sizes="100vw") |

TypeScript

Full TypeScript support with exported types:

import type {
  PixelFiddlerImageProps,
  PixelFiddlerContextValue,
  TransformationOptions,
  ResizeOptions,
  FormatOptions,
  EffectOptions,
  CropOptions,
  BorderOptions,
  TextOptions,
  WatermarkOptions,
  PixelFiddlerConfig,
} from '@pixelfiddler/react';

Related

• @pixelfiddler/core - Core utilities for building transformation URLs

License

MIT