The mask-image property specifies an image (or set of images) that is used as a mask to control the visibility of an element’s painted content. Conceptually the mask defines, on a per-pixel basis, how much of the element’s pixels are shown: areas of the mask that are “opaque” reveal the element and areas that are “transparent” hide it. Because it is a painting operation, using mask-image does not change the element’s layout boxes or DOM geometry — it only affects the final rendered pixels that the user sees.

In practice mask-image is often used where you want soft or complex edges, feathered fades, or non-rectangular visibility that cannot be achieved with simple clipping. Compared to geometric clipping with clip-path, which slices the element into a defined shape, mask-image operates at pixel precision so you can create smooth transitions, drop-off gradients, and partially transparent regions. Likewise, when you combine a mask with a background visual (for example a background picture), the mask modulates the appearance of that background as it modulates the element’s entire painting, so it is complementary to things applied by background-image.

mask-image is controlled and refined by the other mask-related properties that determine how the mask content is scaled, positioned and composed. For example, mask-size and mask-repeat change how the mask image is fitted and tiled relative to the element, while mask-mode affects whether the mask uses alpha channels or luminance to compute coverage. There is also a shorthand that bundles multiple mask settings together; using these properties in combination lets you achieve a wide range of visual masking effects without changing the document structure.

When applying masks keep performance and semantics in mind: masks can force extra offscreen rendering and rasterization steps, especially when they are large, use complex images, or change frequently (animated masks are particularly costly). Masks affect the visual outcome and what users perceive, which can influence accessibility — for instance, important content hidden by a mask might still be reachable to assistive technologies even though it is visually obscured, so be deliberate about using masking for purely decorative effects. Finally, masks interact with compositing and painting order, so be mindful of how they combine with other effects such as filters, shadows, and opacity when crafting your final appearance.