📐 Mastering mask-size in CSS

📌 What Is mask-size?

The mask-size property controls how large the mask image appears when applied to an element. It works similarly to background-size, determining how the mask graphic scales and covers the element's box.
With mask-size, you can scale your stencil, shape, gradient, or pattern to achieve the exact masking effect you want. 🎭✨

>>“mask-size lets you scale your mask like a stencil — bigger, smaller, stretched, or perfectly fitted.”

🧩 Basic Syntax

Basic Syntax

mask-size: auto | <length> | <percentage> | cover | contain;
mask-size: <width> <height>;
mask-size: 50px 80px;
mask-size: 100% 50%;

✔ You can define one or two values
✔ Applied similarly to background-size
✔ Supports keywords like cover and contain

🎯 All mask-size Values Explained

ValueDescription
autoUses intrinsic mask image size
50px, 30%Exact width or scaled by percentage
50px 80pxCustom width and height
coverMask covers entire element (may crop)
containMask fits inside element without cropping

🧪 Example: Default Size

auto size

.shape {
  mask-image: url(mask-heart.png);
  mask-size: auto;
}

✔ Mask displays at its natural image size.

🧪 Example: Scaling the Mask

Scaled mask

.icon {
  mask-image: url(star.svg);
  mask-size: 40px;
}

✔ Mask scales to 40px width (height auto-adjusts).

🧪 Example: Setting Width & Height

Custom width & height

.stencil {
  mask-image: url(shape.png);
  mask-size: 100px 150px;
}

✔ Perfect for custom stencil proportions.

🧪 Example: Using Percentages

Percentage size

.hero {
  mask-image: url(mask-overlay.png);
  mask-size: 100% 60%;
}

✔ Mask fills full width and 60% of the element's height.

🎨 Using cover and contain

✔ cover

cover example

.cover-mask {
  mask-image: url(mask-shape.png);
  mask-size: cover;
}

✔ Mask fills and covers the entire area (cropping possible).

✔ contain

contain example

.contain-mask {
  mask-image: url(mask-shape.png);
  mask-size: contain;
}

✔ Mask fits fully inside the element (no cropping).

🧪 Example: Tile Pattern Mask with mask-repeat

Pattern tiling

.pattern {
  mask-image: url(tile.png);
  mask-size: 40px 40px;
  mask-repeat: repeat;
}

✔ Creates custom patterned masks.

🔥 Example: Animated Mask Scaling

Animated mask-size

@keyframes pulseMask {
  0%   { mask-size: 80px; }
  100% { mask-size: 120px; }
}

.pulse {
  mask-image: radial-gradient(circle, white 50%, transparent);
  animation: pulseMask 1s infinite alternate;
}

✔ Produces a pulsing spotlight reveal effect.

🌈 Advanced Example: mask-size + mask-position

Moving + scaling spotlight

@keyframes spotlight {
  0% {
    mask-size: 20% 20%;
    mask-position: 0% 50%;
  }
  100% {
    mask-size: 40% 40%;
    mask-position: 100% 50%;
  }
}

.reveal {
  mask-image: radial-gradient(circle, white 60%, transparent);
  animation: spotlight 2s infinite alternate;
}

✔ Dynamic spotlight sweep animation.
✔ Great for loaders, reveal cards, and transitions.

🛠️ Best Practices

  • Use auto when you want original mask proportions
  • Use cover for full-section masking effects
  • Use contain to preserve mask shape
  • Combine with mask-position for perfect alignment
  • For tiling patterns, pair with mask-repeat
  • Avoid extremely large mask-size values (performance impact)

⚠️ Browser Support

  • ✔ Chrome
  • ✔ Safari
  • ✔ Edge
  • ⚠️ Firefox requires -webkit-mask-size

Note

For cross-browser support, define both mask-size and -webkit-mask-size.

🔍 Debugging Tips

  • If mask looks stretched → try contain instead of cover
  • If mask is too small → use pixel or percentage values
  • If tiling breaks → check mask-repeat
  • Preview mask scaling using DevTools

🔗 Helpful Resources

>>“mask-size gives you total control over how your visual mask scales — precision meets creativity.” 🎭✨