Integrations

PixelFiddler provides official SDK packages to help you integrate image transformations and optimizations into your applications. These packages handle URL generation, responsive images, and framework-specific optimizations.

Available SDKs

Package	Best For	Key Features
@pixelfiddler/core	Any JavaScript/TypeScript project	URL building, responsive attributes, full control
@pixelfiddler/next	Next.js applications	Drop-in Image replacement, automatic optimization
@pixelfiddler/react	React applications (non-Next.js)	<img> wrapper, responsive srcset, lazy loading

Transformations API

All SDKs accept a transformations object that lets you modify images on-the-fly. This section describes all available transformation options.

Resize

Control the dimensions and scaling behavior of your images.

Option	Type	Description
width	number	Target width in pixels (1-4096)
height	number	Target height in pixels (1-4096)
dpr	1 | 2 | 3 | 4	Device pixel ratio for high-density displays
mode	'FILL' | 'FIT' | 'PAD'	Resize strategy (see below)
background	string	Background color for PAD mode (hex, e.g., #ffffff)

Resize Modes:

• FILL – Resize to fill the exact dimensions, cropping if necessary
• FIT – Resize to fit within the dimensions, preserving aspect ratio
• PAD – Resize to fit within dimensions and pad with background color

transformations: {
  width: 800,
  height: 600,
  mode: 'FIT',
  background: '#ffffff'
}

Format and Quality

Control the output format and compression quality.

Option	Type	Description
format	'JPG' | 'PNG' | 'WEBP' | 'AVIF' | 'GIF'	Output image format
quality	number	Compression quality (1-100, higher is better)
stripMetadata	boolean	Remove EXIF and other metadata from output

transformations: {
  format: 'WEBP',
  quality: 85,
  stripMetadata: true
}

Effects

Apply visual effects to your images.

Option	Type	Description
blur	number	Gaussian blur intensity (0-100)
brightness	number	Brightness adjustment (0-100, 50 is neutral)
contrast	number	Contrast adjustment (0-100, 50 is neutral)
saturation	number	Saturation adjustment (0-100, 50 is neutral)
sharpen	number	Sharpen intensity (0-100)
noise	number	Add noise/grain effect (0-100)
grayscale	boolean	Convert image to grayscale
sepia	boolean	Apply sepia tone effect
rotate	0 | 90 | 180 | 270	Rotate image clockwise by degrees

transformations: {
  blur: 20,
  brightness: 60,
  grayscale: true
}

Border

Add borders and rounded corners to your images.

Option	Type	Description
border.width	number	Border width in pixels
border.color	string	Border color (hex, e.g., #000000)
border.radius	number	Corner radius in pixels (1-2000)

transformations: {
  border: {
    width: 2,
    color: '#000000',
    radius: 8
  }
}

Crop

Crop images with automatic or manual focus points.

Simple Crop with Auto Focus:

transformations: {
  crop: {
    type: 'SIMPLE',
    width: 400,
    height: 300,
    focus: {
      type: 'AUTO',
      strategy: 'SMART'  // 'CENTER' | 'SMART' | 'DETAIL'
    },
    afterResize: true  // Apply crop after resize transformations
  }
}

Simple Crop with Manual Position:

transformations: {
  crop: {
    type: 'SIMPLE',
    width: 400,
    height: 300,
    focus: {
      type: 'SPECIFIED',
      position: { x: 50, y: 50 }  // Percentage from top-left
    }
  }
}

Object Detection Crop:

Automatically detect and crop around faces or upper bodies.

transformations: {
  crop: {
    type: 'OBJECT',
    objectType: 'FACE',  // 'FACE' | 'UPPER_BODY'
    width: 400,
    height: 300
  }
}

Text Overlay

Add text overlays to your images.

Option	Type	Description
text.text	string	The text content to display
text.color	string	Text color (hex)
text.opacity	number	Text opacity (0-100)
text.size	number	Text size as percentage of image (1-100)
text.font	string	Font family name
text.fontSize	number	Font size in pixels
text.position	Position	Text position (see Position Values below)
text.background	string	Background color behind text (hex)
text.backgroundOpacity	number	Background opacity (0-100)

transformations: {
  text: {
    text: 'Copyright 2024',
    color: '#ffffff',
    opacity: 80,
    fontSize: 24,
    position: 'BOTTOM_RIGHT',
    background: '#000000',
    backgroundOpacity: 50
  }
}

Watermark

Add predefined watermarks from your PixelFiddler Dashboard.

Option	Type	Description
watermark.name	string	Watermark name (defined in Dashboard)
watermark.opacity	number	Watermark opacity (0-100)
watermark.size	number	Size as percentage of image (1-100)
watermark.width	number	Explicit width in pixels
watermark.height	number	Explicit height in pixels
watermark.position	Position	Watermark position (see Position Values below)

transformations: {
  watermark: {
    name: 'logo',
    opacity: 50,
    size: 25,
    position: 'BOTTOM_RIGHT'
  }
}

Position Values

Used for text.position and watermark.position:

'TOP_LEFT'     'TOP'        'TOP_RIGHT'
'LEFT'         'CENTER'     'RIGHT'
'BOTTOM_LEFT'  'BOTTOM'     'BOTTOM_RIGHT'
'AUTO'

Special Options

Option	Type	Description
original	boolean	Return the original image without any transformations
alias	string	Use a predefined transformation alias from your Dashboard

// Return original image
transformations: { original: true }

// Use predefined alias
transformations: { alias: 'thumbnail' }

TypeScript Support

All SDKs provide full TypeScript support. Import types from any package:

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