npm package: @pixelfiddler/react
Description: React components for PixelFiddler image transformation SDK
Author: PixelFiddler
Latest version: 1.0.3

# @pixelfiddler/react

React components for [PixelFiddler](https://pixel-fiddler.com) image transformations with automatic responsive image support.

## Installation

```bash
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

```tsx
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.

```tsx
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.

```tsx
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

```tsx
<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:

```tsx
<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`:

```tsx
<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

```tsx
<PixelFiddlerImage
  src="https://example.com/photo.jpg"
  alt="Custom breakpoints"
  sizes="100vw"
  deviceBreakpoints={[480, 768, 1024, 1440, 1920]}
  imageBreakpoints={[]}
/>
```

### Disable Responsive Behavior

```tsx
<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

```tsx
<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:

```typescript
import type {
  PixelFiddlerImageProps,
  PixelFiddlerContextValue,
  TransformationOptions,
  ResizeOptions,
  FormatOptions,
  EffectOptions,
  CropOptions,
  BorderOptions,
  TextOptions,
  WatermarkOptions,
  PixelFiddlerConfig,
} from '@pixelfiddler/react';
```

## Related

- [@pixelfiddler/core](https://www.npmjs.com/package/@pixelfiddler/core) - Core utilities for building transformation URLs

## License

MIT