React SDK

The @pixelfiddler/react package provides a React image component with built-in PixelFiddler optimizations. It automatically handles responsive srcset generation and image transformations.

This package should work with any React project. For Next.js applications, use the Next.js SDK instead for better integration with the Next.js Image component.

You can view the source code on GitHub.

Installation

npm install @pixelfiddler/react

You can also use pnpm or yarn:

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

Getting Started

Import the PixelFiddlerImage component and use it like a regular <img> tag:

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

function App() {
  return (
    <PixelFiddlerImage
      src="https://media.pixelfiddler.com/photos/hero.jpg"
      alt="Hero image"
      width={800}
      transformations={{ format: 'WEBP', quality: 85 }}
    />
  );
}

The component will automatically generate optimized srcset attributes for different screen densities.

Using the Provider

If you’re using multiple images from the same PixelFiddler source, wrap your app (or part of it) with PixelFiddlerProvider to avoid repeating the base URL:

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

function App() {
  return (
    <PixelFiddlerProvider config={{ baseUrl: 'https://media.pixelfiddler.com' }}>
      <Header />
      <Gallery />
      <Footer />
    </PixelFiddlerProvider>
  );
}

function Gallery() {
  return (
    <div className="gallery">
      {/* These images inherit baseUrl from the provider */}
      <PixelFiddlerImage src="/photos/image1.jpg" alt="Image 1" width={400} />
      <PixelFiddlerImage src="/photos/image2.jpg" alt="Image 2" width={400} />
      <PixelFiddlerImage src="/photos/image3.jpg" alt="Image 3" width={400} />
    </div>
  );
}

The provider accepts the following configuration:

Option	Type	Default	Description
baseUrl	string	—	Default base URL for all nested images
maxDpr	number	2	Maximum device pixel ratio for srcset generation

Component Props

The PixelFiddlerImage component accepts all standard HTML img attributes like className, style, loading, etc.

Additionally, it accepts these PixelFiddler-specific props:

Prop	Type	Default	Description
src	string	—	Image path. Can be relative (appended to baseUrl) or absolute
baseUrl	string	—	PixelFiddler endpoint URL. Can be set via provider instead
width	number	—	Display width in pixels. Enables DPR-based srcset (1x, 2x)
sizes	string	—	Standard sizes attribute. Enables width-based srcset
transformations	object	—	Image transformations to apply
responsive	boolean	true	Whether to generate srcset automatically
deviceBreakpoints	number[]	—	Custom device width breakpoints
imageBreakpoints	number[]	—	Custom image width breakpoints

Responsive Images

The component generates responsive srcset attributes automatically based on the props you provide.

Fixed-Width Images

When you specify a width prop, the component generates srcset with DPR descriptors for crisp display on retina screens:

<PixelFiddlerImage
  src="/photos/avatar.jpg"
  alt="User avatar"
  width={150}
  transformations={{ format: 'WEBP' }}
/>

This generates:

<img
  src="...?w=150&f=WEBP"
  srcset="...?w=150&f=WEBP 1x, ...?w=300&f=WEBP 2x"
  width="150"
/>

Fluid Images

When you specify a sizes prop instead, the component generates srcset with width descriptors for images that scale with the viewport:

<PixelFiddlerImage
  src="/photos/hero.jpg"
  alt="Hero banner"
  sizes="(max-width: 768px) 100vw, 50vw"
  transformations={{ format: 'WEBP', quality: 85 }}
/>

This generates srcset with multiple width variants (320w, 640w, 768w, 1024w, etc.) so the browser can pick the best size.

Disabling Responsive Behavior

If you need a single fixed image without srcset generation, set responsive to false:

<PixelFiddlerImage
  src="/photos/thumbnail.jpg"
  alt="Thumbnail"
  responsive={false}
  transformations={{ width: 200, height: 200, format: 'WEBP' }}
/>

Custom Breakpoints

You can customize the breakpoints used for srcset generation:

<PixelFiddlerImage
  src="/photos/hero.jpg"
  alt="Hero"
  sizes="100vw"
  deviceBreakpoints={[480, 768, 1024, 1440, 1920]}
  transformations={{ format: 'WEBP' }}
/>

Applying Transformations

Use the transformations prop to resize, optimize, and apply effects to your images. Here are some examples:

Format and Quality

<PixelFiddlerImage
  src="/photos/product.jpg"
  alt="Product"
  width={600}
  transformations={{
    format: 'WEBP',
    quality: 85,
  }}
/>

Resize with Mode

<PixelFiddlerImage
  src="/photos/product.jpg"
  alt="Product thumbnail"
  responsive={false}
  transformations={{
    width: 300,
    height: 300,
    mode: 'FIT',
    format: 'WEBP',
  }}
/>

Effects

<PixelFiddlerImage
  src="/photos/background.jpg"
  alt="Background"
  sizes="100vw"
  transformations={{
    blur: 20,
    brightness: 70,
    format: 'WEBP',
  }}
/>

For all available transformation options, see the Transformations API.

TypeScript

The package includes full TypeScript support. You can import types for props and configuration:

import type {
  PixelFiddlerImageProps,
  PixelFiddlerContextValue,
  TransformationOptions,
  PixelFiddlerConfig,
} from '@pixelfiddler/react';