Imgix

Real-time image processing and CDN delivery via URL parameters. No server-side processing needed - transformations happen at the edge.

Quick Start

URL Structure

https://your-source.imgix.net/path/to/image.jpg?w=400&h=300&fit=crop

Components:

• Source: Your imgix subdomain
• Path: Image path in your origin (S3, GCS, web folder)
• Parameters: Transformation query string

Basic Example

const imgixDomain = 'your-source.imgix.net';

function imgixUrl(path, params = {}) {
  const url = new URL(`https://${imgixDomain}${path}`);
  Object.entries(params).forEach(([key, value]) => {
    url.searchParams.set(key, value);
  });
  return url.toString();
}

// Usage
const url = imgixUrl('/products/shoe.jpg', {
  w: 400,
  h: 300,
  fit: 'crop',
  auto: 'format,compress',
});
// https://your-source.imgix.net/products/shoe.jpg?w=400&h=300&fit=crop&auto=format%2Ccompress

Core Parameters

Sizing

?w=400           # Width
?h=300           # Height
?w=400&h=300     # Both (may crop/letterbox based on fit)
?ar=16:9&w=800   # Aspect ratio with width

Fit Modes

?fit=clip        # Resize to fit, no crop (default)
?fit=crop        # Resize and crop to exact size
?fit=fill        # Resize to fit, fill with background
?fit=fillmax     # Like fill, never upscale
?fit=max         # Resize to fit, never upscale
?fit=min         # Resize, at least one dimension matches
?fit=scale       # Stretch to exact size (distorts)
?fit=clamp       # Like clip, never upscale
?fit=facearea    # Crop to detected face

Crop & Focus

?crop=faces      # Crop to faces
?crop=entropy    # Crop to high-detail area
?crop=edges      # Crop to edges
?crop=top        # Crop from top
?crop=bottom,left # Crop from bottom-left

# Focal point (0-1 coordinates)
?fp-x=0.3&fp-y=0.7&fit=crop

# Face detection + crop
?fit=facearea&facepad=1.5

Auto Optimization

?auto=format     # Best format for browser (WebP, AVIF)
?auto=compress   # Optimal compression
?auto=format,compress  # Both (recommended)

This automatically:

• Serves WebP to Chrome/Firefox, AVIF where supported
• Applies optimal compression per format
• Maintains quality while reducing file size

Quality & Format

?q=75            # Quality 1-100 (default varies by format)
?fm=webp         # Force WebP format
?fm=avif         # Force AVIF format
?fm=jpg          # Force JPEG
?fm=png          # Force PNG
?lossless=true   # Lossless compression (PNG, WebP)

Effects & Adjustments

Color

?bri=20          # Brightness (-100 to 100)
?con=30          # Contrast (-100 to 100)
?sat=50          # Saturation (-100 to 100)
?hue=180         # Hue rotation (0-359)
?gam=1.5         # Gamma (0-10)
?exp=10          # Exposure (-100 to 100)
?vib=20          # Vibrance (-100 to 100)

Filters

?blur=50         # Gaussian blur (0-2000)
?sharp=10        # Sharpen (0-100)
?sepia=80        # Sepia tone (0-100)
?monochrome=blue # Monochrome with tint
?htn=0           # Halftone
?px=10           # Pixelate

Stylize

?duotone=000000,663399  # Duotone (shadow,highlight)
?blend=663399&bm=multiply  # Color blend

Watermarks & Overlays

# Image overlay
?mark=watermark.png&mark-w=100&mark-align=bottom,right&mark-pad=10

# Text overlay
?txt=Hello%20World&txt-size=24&txt-color=ffffff&txt-align=center
?txt=Copyright&txt-font=Helvetica&txt-pad=20

# Blend modes
?blend=overlay.png&bm=multiply&ba=center,middle

Responsive Images

srcset Generation

function generateSrcset(path, sizes = [400, 800, 1200, 1600]) {
  return sizes
    .map((w) => `${imgixUrl(path, { w, auto: 'format,compress' })} ${w}w`)
    .join(', ');
}

// Usage in React
function ResponsiveImage({ src, alt, sizes }) {
  return (
    <img
      src={imgixUrl(src, { w: 800, auto: 'format,compress' })}
      srcSet={generateSrcset(src)}
      sizes={sizes}
      alt={alt}
    />
  );
}

With Device Pixel Ratio

?w=400&dpr=2     # 800px actual, for 2x displays
?w=400&dpr=3     # 1200px actual, for 3x displays

function generateDprSrcset(path, width) {
  return [1, 1.5, 2, 3]
    .map((dpr) => `${imgixUrl(path, { w: width, dpr, auto: 'format,compress' })} ${dpr}x`)
    .join(', ');
}

JavaScript SDK

npm install @imgix/js-core

import ImgixClient from '@imgix/js-core';

const client = new ImgixClient({
  domain: 'your-source.imgix.net',
  secureURLToken: 'your-token',  // Optional, for signed URLs
});

// Build URL
const url = client.buildURL('/image.jpg', {
  w: 400,
  h: 300,
  fit: 'crop',
  auto: 'format,compress',
});

// Generate srcset
const srcset = client.buildSrcSet('/image.jpg', {
  auto: 'format,compress',
}, {
  widths: [400, 800, 1200, 1600],
});

React SDK

npm install @imgix/react

import Imgix from '@imgix/react';

function ProductImage({ path }) {
  return (
    <Imgix
      src={`https://your-source.imgix.net${path}`}
      sizes="(min-width: 1024px) 50vw, 100vw"
      imgixParams={{
        fit: 'crop',
        ar: '16:9',
        auto: 'format,compress',
      }}
      htmlAttributes={{
        alt: 'Product image',
        loading: 'lazy',
      }}
    />
  );
}

With Background Image

import { Background } from '@imgix/react';

function Hero({ imagePath }) {
  return (
    <Background
      src={`https://your-source.imgix.net${imagePath}`}
      imgixParams={{ auto: 'format,compress', fit: 'crop' }}
      className="hero-section"
    >
      <h1>Welcome</h1>
    </Background>
  );
}

Next.js Integration

Custom Loader

// next.config.js
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './imgix-loader.js',
  },
};

// imgix-loader.js
export default function imgixLoader({ src, width, quality }) {
  const url = new URL(`https://your-source.imgix.net${src}`);
  url.searchParams.set('w', width.toString());
  url.searchParams.set('q', (quality || 75).toString());
  url.searchParams.set('auto', 'format,compress');
  return url.toString();
}

import Image from 'next/image';

function ProductImage({ src }) {
  return (
    <Image
      src={src}
      width={800}
      height={600}
      alt="Product"
    />
  );
}

Common URL Patterns

Thumbnail

?w=150&h=150&fit=crop&crop=faces&auto=format,compress

Hero Image

?w=1920&h=600&fit=crop&crop=entropy&auto=format,compress&q=80

Avatar

?w=100&h=100&fit=facearea&facepad=2&mask=ellipse&auto=format,compress

Card Image

?w=400&h=300&fit=crop&ar=4:3&auto=format,compress

Product Gallery

?w=800&fit=max&auto=format,compress&bg=ffffff

Blurred Placeholder (LQIP)

?w=20&blur=200&auto=format,compress&q=30

Signed URLs

For private images or to prevent URL tampering:

import ImgixClient from '@imgix/js-core';

const client = new ImgixClient({
  domain: 'your-source.imgix.net',
  secureURLToken: process.env.IMGIX_SECURE_TOKEN,
});

// Signed URL
const signedUrl = client.buildURL('/private/image.jpg', {
  w: 400,
  auto: 'format,compress',
});

Performance Tips

1. Always use

   auto=format,compress

   - Let imgix choose best format
2. Specify width - Don't serve larger than needed
3. Use srcset - Serve appropriate sizes for device
4. Consider DPR - Use

   dpr

   for high-density displays
5. Set cache headers - Images are CDN-cached
6. Use LQIP - Low-quality placeholders for perceived performance

Pricing Note

Imgix charges based on:

• Master images (origin images accessed)
• Unique transformations cached
• Bandwidth delivered

Use consistent transformation parameters to maximize cache hits.