Skip to main content

Background Alpha

Use the background_alpha transformation to control the alpha channel of the active background color.

Overview​

background_alpha is useful when a transformation creates new canvas space and you want the fill to be partially transparent. Pair it with background to choose the color and use an output format that can preserve alpha when transparency needs to survive delivery.

Syntax​

FieldValue
Canonical parameterbackground_alpha
Aliasbga
Accepted valuesNumber from 0 through 1

Example​

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?rotate=12&background=2E38E6&background_alpha=0.35&format=png
image.url({
  rotate: 12,
  background: '2E38E6',
  background_alpha: 0.35,
  format: 'png',
});
imgwire images url img_123 --rotate 12 --background 2E38E6 --background-alpha 0.35 --format png

Live examples​

Solid background35% alpha background
Demo image rotated with a solid blue backgroundDemo image rotated with a translucent blue background

Best practices​

  • Use format=png when you need the delivered result to preserve transparency.
  • Keep alpha values explicit so future readers know whether the background should be solid or translucent.
  • Test the result on the actual page background where the image will appear.

Common mistakes​

  • Setting background_alpha without a transform that needs background fill.
  • Requesting a format that cannot preserve the transparency you expect.
  • Using translucent backgrounds for images that must sit cleanly on varied page colors.

Last updated at: May 9, 2026