← Back to Chapters

CSS Image Masking

?️ CSS Image Masking

⚡ Quick Overview

CSS Image Masking lets you control which parts of an element are visible by applying a mask image or gradient. The mask defines a shape:

  • White areas of the mask are fully visible.
  • Black areas are fully hidden (transparent).
  • Gray areas are partially transparent (semi-visible).

Masking is perfect for creative effects like circular crops, text reveals, and complex shapes without actually editing the original image.

? Key Concepts

  • mask-image — defines the image or gradient used as the mask.
  • mask-repeat — controls repetition of the mask (similar to background-repeat).
  • mask-position — controls where the mask is placed.
  • mask-size — controls how big the mask is.
  • -webkit-mask-* — WebKit-prefixed versions for better browser support (Safari, some Chromium browsers).

? Basic Syntax

The simplest way to apply a mask is using an external image file (PNG/SVG with transparency):

? View Basic mask-image Syntax 
/* Apply a custom shape mask to an image element */
img.profile-photo {
mask-image: url("mask-shape.png");
mask-repeat: no-repeat;
mask-position: center;
mask-size: contain;
-webkit-mask-image: url("mask-shape.png");
-webkit-mask-repeat: no-repeat;
-webkit-mask-position: center;
-webkit-mask-size: contain;
}

You can also use gradients instead of external images to build smooth, dynamic masking shapes directly in CSS.

? View Gradient Mask Example 
/* Fade an image from left (visible) to right (transparent) */
.banner {
mask-image: linear-gradient(to right, black 40%, transparent 100%);
mask-repeat: no-repeat;
-webkit-mask-image: linear-gradient(to right, black 40%, transparent 100%);
-webkit-mask-repeat: no-repeat;
}

? Important Mask Properties

These are the core properties you will use when working with CSS masking:

Property Description
mask-image Defines the mask shape/image (PNG, SVG, gradient, etc.).
mask-repeat Controls how the mask repeats (no-repeat, repeat, repeat-x, repeat-y).
mask-position Sets the position of the mask inside the element (center, top, etc.).
mask-size Controls the size of the mask (cover, contain, or custom values).
mask-composite Controls how multiple masks blend with each other.

? Circular Spotlight Mask

This example uses a radial-gradient mask to reveal only a circular area in the center of the image.

Masked laptop image

Only the center circular region is fully visible. The area outside the circle gradually fades to transparent because of the gradient. The actual image is still full-sized — only its visibility is being controlled.

? Code for the Live Example

? View Live Example Code 
/* Circular spotlight mask using radial-gradient */
.masked-photo {
width: 100%;
display: block;
mask-image: radial-gradient(circle at center, black 0, black 40%, transparent 60%);
-webkit-mask-image: radial-gradient(circle at center, black 0, black 40%, transparent 60%);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-position: center;
-webkit-mask-position: center;
mask-size: cover;
-webkit-mask-size: cover;
}

? How CSS Image Masking Works

mask-image behaves similarly to background-image:

  • You can pass a URL (PNG/SVG) or a CSS gradient as the source.
  • The mask is placed on top of the element and controls visibility pixel by pixel.
  • Where the mask is opaque, the element is visible; where the mask is transparent, the element is hidden.

For better support, especially in Safari, always include the -webkit-mask-* versions of the properties.

? Common Use Cases

  • Creating circular or polygonal avatar images without editing the original file.
  • Building text reveal animations (mask moves, content stays fixed).
  • Highlighting a specific part of a large photo with a spotlight effect.
  • Combining multiple masks for complex UI effects.

? Tips & Best Practices

  • Use PNG or SVG with transparency for precise masking shapes.
  • Gradients like linear-gradient and radial-gradient are great for soft edges and fades.
  • Always test with both mask-* and -webkit-mask-* for cross-browser support.
  • Remember: masking does not resize the image; it only hides parts of it.
  • When designing masks, think in terms of opacity: black = visible in code examples above, but in some designs white is used as visible; be consistent with your design.
  • For advanced layouts, explore mask-composite to combine multiple mask layers creatively.

? Try It Yourself

  1. Create a simple image and apply a circular mask using radial-gradient. Make the edges soft by fading to transparent.
  2. Design a heart-shaped SVG file and use it as a mask-image on any photo.
  3. Create a wide banner and apply a repeating pattern mask using mask-image with mask-repeat: repeat-x;.
  4. Experiment with mask-position and mask-size to move and scale your mask over the same image.
  5. Test your mask in different browsers and add -webkit-mask-image to fix any compatibility issues.