Skip to main content

Background

Use the background transformation to set the fill color used when a delivered image variant needs canvas space or when a transparent image should be flattened onto a color.

Overview​

Background color matters when an image is contained inside fixed dimensions, rotated, padded, extended, or flattened from transparent input. Imgwire applies the color to the delivered variant only; it does not change the original uploaded image.

Syntax​

FieldValue
Canonical parameterbackground
Aliasbg
Accepted valuesHex color values, such as F3F4F6 or URL-encoded #F3F4F6

Example​

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{transparent_image_id}?background=F3F4F6&format=png&width=420
image.url({
  width: 420,
  background: 'F3F4F6',
  format: 'png',
});
imgwire images url img_123 --width 420 --background F3F4F6 --format png

Live examples​

These examples use a transparent PNG source image. The background value fills the transparent pixels in the delivered variant.

White backgroundGray backgroundBlue background
Transparent PNG icon flattened onto a white backgroundTransparent PNG icon flattened onto a light gray backgroundTransparent PNG icon flattened onto an Imgwire blue background

Best practices​

  • Use background whenever resizing_type=contain creates letterboxing.
  • Use background to flatten transparent PNG or WebP images onto a predictable color.
  • Match the background to the page or component surface where the image will render.
  • URL-encode # as %23 if you include it in a query string color value.

Common mistakes​

  • Expecting background to be visible when no transform creates extra canvas space.
  • Using a page-specific background color in a reusable image URL that appears on multiple surfaces.
  • Forgetting to pair transparent outputs with the correct format when transparency matters.

Last updated at: May 9, 2026