Extend Aspect Ratio

Use the extend_aspect_ratio transformation to add canvas space until a delivered image variant reaches a target aspect ratio.

Overview

extend_aspect_ratio is useful when source images vary but your UI expects a consistent frame. Instead of cropping content away, Imgwire pads the delivered variant to the requested ratio and centers the added space around the source image.

Syntax

Field	Value
Canonical parameter	extend_aspect_ratio
Aliases	exar, extend_ar
Accepted values	Ratio number, width:height, or an SDK object

Example

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?extend_aspect_ratio=16:9&background=F3F4F6

image.url({
  extend_aspect_ratio: '16:9',
  background: 'F3F4F6',
  format: 'auto',
  quality: 'auto',
});

imgwire images url img_123 --extend-aspect-ratio 16:9 --background F3F4F6

Live examples

Original

16:9 frame

1:1 frame

Best practices

• Use extend_aspect_ratio when preserving the whole image matters more than filling the frame.
• Use background to make the added canvas match your UI.
• Use Crop when the target frame should be filled by trimming image content.

Common mistakes

• Expecting extend_aspect_ratio to crop. It pads to the requested ratio.
• Forgetting that very different source ratios can create large visible bands.
• Using the transform without a background color when the default fill does not match the surface.

Related pages

• Extend
• Background
• Crop

Last updated at: May 9, 2026