Your images,
optimized.
Automatic WebP, AVIF, PNG & JPEG conversion for Payload CMS v3. Resize on upload. Zero config required.
Powerful features.
Zero setup.
Any format, automatically.
Converts inputs on the fly. Say goodbye to manual formatting constraints.
Resize instantly.
Maintains aspect ratios perfectly while shrinking massive 4k uploads down to specs.
The modern standard.
Serve next-gen formats like WebP or AVIF out of the box, slashing bandwidth costs by up to 80% with unrivaled precision.
Seamless Admin UI.
Editors can select formats directly from the media sidebar, complete with real-time compression savings analytics directly in Payload.
Everything you need.
Nothing you don't.
A complete suite of tools to handle your image pipeline exactly how you want it. Zero compromises.
Conversion & Compression
Automatic conversion
Converts uploads to WebP, AVIF, PNG, or JPEG on create/update.
Per-image format selection
Editors choose the desired format from a sidebar dropdown.
Global default format
Falls back to defaultFormat when no per-image selection is made.
Configurable quality
Global quality setting (0-100) with per-format overrides.
Per-format Sharp options
Fine-grained control over WebP, AVIF, PNG, and JPEG encoding.
Resize Pipeline
Image resizing
Constrain dimensions via global config or per-image sidebar inputs.
Aspect ratio preservation
Resize uses fit: 'inside' to maintain proportions.
No upscaling
withoutEnlargement: true prevents small images from being enlarged.
Format-aware re-encoding
Resize-only operations skip format change to avoid quality loss.
Admin UI Experience
Re-conversion without re-upload
Change format on existing images directly from the admin panel.
File size savings display
Shows percentage and byte savings after a successful conversion.
Oversize image detection
Warns editors when images exceed a custom pixel threshold.
Auto-fill resize suggestion
One-click button sets max width to the threshold value.
Collapsible resize panel
Clean sidebar UI with auto-expand and '(active)' badge.
Safety & Guards
Quality degradation warnings
UI and server-side warnings for lossy-to-lossy re-conversion.
SVG and GIF skip
Vector and animated images are intelligently passed through unchanged.
Max file size guard
Files exceeding maxFileSize are skipped with a clear warning.
Kill switch
disabled: true stops conversion while keeping database schema consistent.
Double-conversion warning
Detects conflicting collection-level formatOptions in Payload.
Graceful failure
Sharp errors are caught safely; original uploads are preserved.
Architecture
Schema consistency
Fields are always injected, even when disabled, to prevent sync issues.
Hook prepend order
Conversion seamlessly runs before other Payload beforeOperation hooks.
No Sharp dependency
Lightweight—reuses Payload's native managed Sharp instance.
Original file size tracking
Hidden field securely powers the granular savings UI.
Three package exports
Main, /types, and /client entry points for ultra-clean imports.
Three lines.
Infinite performance.
Drop the plugin into your Payload config. It hooks into the upload cycle natively, utilizing Sharp for blazingly fast compression. Zero boilerplate.
- TypeScript ready
- Extends native Payload v3
- Auto-detects image fields
import { buildConfig } from 'payload/config'
import { imageConverterPlugin } from 'payload-img-convert'
export default buildConfig({
plugins: [
imageConverterPlugin({
collections: ['media'],
formats: ['webp', 'avif'],
maxWidth: 1920,
quality: 80,
oversizeThreshold: 2000
})
],
})