Imgix APIsRendering APIMask ImageMask Invert

Mask Invert

mask-invert

Inverts the mask, removing the shape and keeping everything around it. The result is exactly 1 minus the mask, so a shape that mask would have kept becomes a transparent hole — a stencil rather than a crop.

mask-invert works with every mask type: ellipse, corners, poly3 through poly32, and an image URL.

Accepted Values

ValueResult
falseDefault. The mask keeps its shape and discards everything around it.
trueThe mask is inverted. The shape becomes a transparent hole and everything around it is kept.

What is kept

A knockout is exactly the opposite of the mask: wherever the mask would keep a pixel, the knockout removes it, and the other way round.

Behavior when inverted
ellipse, corners, poly3–poly32Drawn as large as the image, so inverting keeps only what lies outside — the corners around an ellipse, or the pieces a rounded rectangle rounds off. To knock a smaller shape out of the middle, use an image mask.
Image masksBrightness is mirrored: white areas are removed, black areas are kept.
fadeFeathered edges fade the same way, mirrored.
padPadding lies outside the shape, so the mask leaves it untouched.
borderDraws along the shape’s edge, outlining the knockout.
Watermarks and textDrawn after the mask, so they are never removed by it.

Filling the transparency

The hole takes mask-bg when you set one, on any format. Without it:

  • on a format that carries transparency (PNG, WebP, AVIF) the hole is transparent;
  • on JPEG and GIF it is filled with white;
  • with auto=compress and no fm, a JPEG source keeps the hole transparent and is delivered as PNG. fm=jpg always fills it.

Under drop-shadow the hole is not filled with the white default — bg backs the shape instead, so the shadow falls along the knockout’s edge.

Demo

Each example adds transparency=grid so the checkerboard makes the hole visible. It is not required to use mask-invert.

mask=ellipse — the baseline. The ellipse is kept and the four corners are discarded.
https://static-a.imgix.net/espresso.jpg?w=300&h=300&fit=crop&fm=png&mask=ellipse&transparency=grid
ellipse (not inverted)

To cut a blend layer or text out of the image rather than a geometric shape, use the knockout blend modes — see blend-mode and txt-blend-mode.