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
| Value | Result |
|---|---|
false | Default. The mask keeps its shape and discards everything around it. |
true | The 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–poly32 | Drawn 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 masks | Brightness is mirrored: white areas are removed, black areas are kept. |
fade | Feathered edges fade the same way, mirrored. |
pad | Padding lies outside the shape, so the mask leaves it untouched. |
border | Draws along the shape’s edge, outlining the knockout. |
| Watermarks and text | Drawn 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=compressand nofm, a JPEG source keeps the hole transparent and is delivered as PNG.fm=jpgalways 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.
Related
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.