Size & Layout Parameters#

Control your image dimensions and layout behavior with powerful sizing parameters. These are the most commonly used transformation options.

Width (w)#

Description#

Set the width of the output image in pixels.

Range#

• Minimum: 1px
• Maximum: 16384px

Usage#

?transform=w:800

Examples#

Resize to 800px width (maintains aspect ratio)

?transform=w:800

---

Height (h)#

Description#

Set the height of the output image in pixels.

Range#

• Minimum: 1px
• Maximum: 16384px

Usage#

?transform=h:600

Examples#

Resize to 600px height (maintains aspect ratio)

?transform=h:600

Combine width and height

?transform=w:800,h:600

When both width and height are specified, the fit parameter determines how the image is resized.

---

Fit Modes#

Description#

When both width and height are specified, the fit parameter determines how the image should be resized to fit within the specified dimensions.

Default#

cover - The image is resized to fill the entire area, cropping if necessary

Available Modes#

contain#

Description: Resize to fit within the specified dimensions while maintaining aspect ratio. The entire image will be visible, potentially with empty space.

?transform=w:400,h:300,fit:contain

Use case: Logos, product images where the entire image must be visible

cover (default)#

Description: Resize to fill the entire specified area while maintaining aspect ratio. The image may be cropped to fit.

?transform=w:400,h:300,fit:cover

Use case: Thumbnails, hero images, cards where consistent dimensions are required

fill#

Description: Ignore aspect ratio and resize to exactly the specified dimensions. The image may be stretched or squashed.

?transform=w:400,h:300,fit:fill

Use case: Specific dimension requirements where distortion is acceptable

inside#

Description: Resize to fit within the specified dimensions. Will only shrink images, never enlarge.

?transform=w:400,h:300,fit:inside

Use case: Ensuring images don't exceed maximum dimensions

outside#

Description: Resize to at least the specified dimensions. Will only enlarge images, never shrink.

?transform=w:400,h:300,fit:outside

Use case: Ensuring images meet minimum dimensions

Fit Modes Comparison#

---

Device Pixel Ratio (DPR)#

Description#

DPR (Device Pixel Ratio) adjusts the actual image size for high-resolution displays while keeping the display size consistent. This is essential for crisp, sharp images on Retina and high-DPI screens.

Range#

• Minimum: 1.0
• Maximum: 4.0
• Default: 1.0

How DPR Works#

The actual image size is calculated by multiplying the specified dimensions by the DPR value:

Actual Image Size = Specified Size × DPR

Examples:

• w:300,dpr:1.0 → Actual width: 300px
• w:300,dpr:2.0 → Actual width: 600px
• w:300,dpr:3.0 → Actual width: 900px

The browser displays the image at the specified size (300px), but downloads a larger image for sharper rendering on high-DPI displays.

Usage#

?transform=w:800,dpr:2.0

Visual Comparison#

Recommended DPR Values#

DPR Usage Examples#

Desktop standard resolution

?transform=w:400,h:300,dpr:2.0

High-resolution Retina mobile

?transform=w:400,h:300,dpr:3.0

Responsive with DPR

?transform=w:800,dpr:2.0,format:auto,fit:cover

---

Common Use Cases#

Responsive Thumbnails#

Square thumbnails for product listings:

?transform=w:200,h:200,fit:cover,dpr:2.0

Hero Images#

High-quality hero images for landing pages:

?transform=w:1920,h:1080,fit:cover,dpr:2.0

Profile Pictures#

Consistent circular profile images:

?transform=w:128,h:128,fit:cover,dpr:3.0

Mobile Optimization#

Optimized images for mobile devices:

?transform=w:375,dpr:3.0,format:auto,fit:cover

Desktop Hero#

Desktop-optimized hero images:

?transform=w:1200,dpr:2.0,format:webp,fit:cover

---

Next Steps#

• Visual Effects - Add rotation, blur, and more
• Region & Output - Extract regions and control output format
• Best Practices - Learn optimization strategies