Skip to main content

Documentation Index

Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

ButterCMS integrates with Filestack to provide powerful image transformation capabilities through URL parameters. Transform images on-the-fly without modifying originals—perfect for responsive images, thumbnails, and optimized delivery.

​
Key benefits

  • No Pre-processing: Transform images at request time
  • CDN Cached: Transformed images are cached globally
  • Original Preserved: Original files remain unchanged
  • Chainable: Combine multiple transformations

​
URL structure

All images in ButterCMS have a CDN URL. Add transformation tasks before the file ID: 
https://cdn.buttercms.com/TASK=option:value/FILE_ID
Original URL: 
https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD
With Transformation: 
https://cdn.buttercms.com/resize=height:300/Lvv0MCF0QhCoKLSuEJzD

​
Chaining transformations

Combine multiple transformations with forward slashes: 
https://cdn.buttercms.com/resize=width:800/rotate=deg:90/quality=value:80/FILE_ID

​
Resize transformations

​
Basic resize

ParameterDescriptionExample
widthTarget width in pixelsresize=width:800
heightTarget height in pixelsresize=height:600
width,heightBoth dimensionsresize=width:800,height:600

​
Resize options

OptionValuesDescription
fitclip, crop, scale, maxHow to fit the image
aligncenter, top, bottom, left, right, facesAlignment for crop/fit
Examples: 
# Resize to max width, maintain aspect ratio
https://cdn.buttercms.com/resize=width:800/FILE_ID

# Resize and crop to exact dimensions
https://cdn.buttercms.com/resize=width:400,height:300,fit:crop/FILE_ID

# Resize with face detection alignment
https://cdn.buttercms.com/resize=width:200,height:200,fit:crop,align:faces/FILE_ID

​
Fit modes

ModeBehavior
clipResize to fit within bounds, maintain aspect ratio (default)
cropResize and crop to exact dimensions
scaleStretch to exact dimensions (may distort)
maxResize to not exceed bounds

​
Crop transformations

​
Basic crop

crop=dim:[x,y,width,height]
Example: 
# Crop starting at (100,50) with 400x300 dimensions
https://cdn.buttercms.com/crop=dim:[100,50,400,300]/FILE_ID

​
Smart crop (face detection)

Automatically crop around detected faces:
Face detection is provided by Filestack’s processing API. Feature availability may vary by plan.
https://cdn.buttercms.com/resize=width:200,height:200,fit:crop,align:faces/FILE_ID

​
Rotation & flip

​
Rotate

rotate=deg:DEGREES
ValueDescription
90Rotate 90° clockwise
180Rotate 180°
270Rotate 270° clockwise
exifAuto-rotate based on EXIF data
Examples: 
https://cdn.buttercms.com/rotate=deg:90/FILE_ID
https://cdn.buttercms.com/rotate=deg:exif/FILE_ID

​
Flip

TaskDescription
flipFlip vertically
flopFlip horizontally
Examples: 
https://cdn.buttercms.com/flip/FILE_ID
https://cdn.buttercms.com/flop/FILE_ID

​
Quality & format

​
Quality compression

Control JPEG/WebP quality (0-100): 
quality=value:QUALITY
Example: 
https://cdn.buttercms.com/quality=value:80/FILE_ID

​
Format conversion

Convert between image formats: 
output=format:FORMAT
FormatUse Case
jpgPhotos, complex images
pngGraphics with transparency
webpModern browsers, best compression
gifAnimations
Example: 
https://cdn.buttercms.com/output=format:webp/FILE_ID

​
Filters & effects

​
Blur

blur=amount:AMOUNT
Amount: 0-20 (higher = more blur) 
https://cdn.buttercms.com/blur=amount:5/FILE_ID

​
Sharpen

sharpen=amount:AMOUNT
Amount: 1-10 (higher = more sharpening) 
https://cdn.buttercms.com/sharpen=amount:10/FILE_ID

​
Grayscale

monochrome

https://cdn.buttercms.com/monochrome/FILE_ID

​
Sepia

sepia=tone:AMOUNT
Tone: 0-100 (percentage of sepia effect) 
https://cdn.buttercms.com/sepia=tone:80/FILE_ID

​
Brightness & contrast

enhance
Auto-enhance brightness and contrast: 
https://cdn.buttercms.com/enhance/FILE_ID

​
Watermarks & overlays

Watermark functionality is provided by Filestack’s processing API. Feature availability may vary by plan.

​
Basic watermark

watermark=file:WATERMARK_FILE_ID,position:POSITION
PositionDescription
topTop center
bottomBottom center
leftLeft center
rightRight center
centerCenter
[top,left]Specific coordinates
Example: 
https://cdn.buttercms.com/watermark=file:WATERMARK_ID,position:bottom/FILE_ID

​
Common transformation recipes

​
Thumbnail (square)

https://cdn.buttercms.com/resize=width:150,height:150,fit:crop/FILE_ID

​
Hero image (optimized)

https://cdn.buttercms.com/resize=width:1920/quality=value:85/output=format:webp/FILE_ID

​
Avatar with face detection

https://cdn.buttercms.com/resize=width:100,height:100,fit:crop,align:faces/FILE_ID

https://cdn.buttercms.com/resize=width:1200/quality=value:80/FILE_ID

​
Card image

https://cdn.buttercms.com/resize=width:400,height:250,fit:crop/FILE_ID

​
Code examples

function getTransformedUrl(originalUrl, transformations) {
  // Extract file ID from URL
  const fileId = originalUrl.split('/').pop();

  // Build transformation string
  const transforms = Object.entries(transformations)
    .map(([key, value]) => {
      if (typeof value === 'object') {
        const params = Object.entries(value)
          .map(([k, v]) => `${k}:${v}`)
          .join(',');
        return `${key}=${params}`;
      }
      return key;
    })
    .join('/');

  return `https://cdn.buttercms.com/${transforms}/${fileId}`;
}

// Usage
const heroUrl = getTransformedUrl(
  'https://cdn.buttercms.com/abc123',
  {
    resize: { width: 1200, height: 600, fit: 'crop' },
    quality: { value: 85 }
  }
);

​
Next steps

Responsive Images

Generate responsive images

Security

Secure your images

Media Library

Media management

Image Compression

Automatic optimization