CSS mask-size Property

Beginner
6 min read
Updated: Oct 2026
3 examples
Live preview
CSS mask-size scaling a mask image with cover, contain, and length values
Definition

Definition and Usage

The mask-size property sets how large a mask-image is drawn. Leave it at its natural size with auto, stretch it with lengths or percentages, or fit the box with cover and contain while keeping the aspect ratio.

The initial value is auto. The property is not inherited. Percentages are relative to the mask positioning area from mask-origin (default padding-box). Pair it with mask-repeat: no-repeat when a smaller size should not tile.

Standard-track.

Not deprecated and not experimental. Unprefixed mask-size is Baseline widely available. Older Safari needed -webkit-mask-size. Gradients have no intrinsic size, so prefer a file or SVG with width and height when studying cover vs contain.

Syntax

CSS Syntax

syntax.css
mask-size: auto | cover | contain | <length> | <percentage> | initial | inherit;

One value sets the width; height becomes auto. Two values set width then height. Separate sizes for multiple mask layers with commas.

Values

Property Values

ValueDescriptionTry it
autoDefault. Keep the mask's natural size (or proportional height)Try it
coverScale to fill the box. May crop. Keeps the aspect ratioTry it
containScale to fit inside the box. May leave gaps. Keeps the aspect ratioTry it
<percentage>Width relative to the positioning area. Example: 50%Try it
<length> <length>Explicit width and height. Example: 100px 60pxTry it
initialResets this property to autoTry it
inheritCopies this property from the parent elementTry it
Approach

How to Use mask-size

Add a mask first, give the box a size, then choose how that mask scales inside it.

  1. Set a mask-image. Size has nothing to scale without a mask.
  2. Give the element a visible area with content or a height, and a background you can see through the mask.
  3. Set mask-size to cover, contain, a length, a percentage, or two values.
  4. For logos and cutouts, also set mask-repeat: no-repeat so a smaller size does not tile.
PieceRequired?Role
mask-imageYesThe paint you are scaling as a mask
A visible boxYesHeight or content so cover and contain have a target
Size keyword or lengthsYescover, contain, auto, or explicit sizes
mask-repeatOftenno-repeat stops tiling when the mask is smaller than the box
mask-positionNoWhere the scaled mask sits, often center with cover
Try it

Live Preview

One box with a fixed-ratio SVG mask over a gradient. Change mask-size and watch how the revealed shape scales.

The SVG mask is 120×80. Gaps mean the mask does not fill the box.

Size

mask-size: cover

Code

CSS Examples

Each snippet adds only what mask-size needs: a mask with a real size, a box, and the size keyword or lengths. Use Try It Yourself for a live editor.

Example 1 — cover

Fill the whole box with the mask. Edges of the SVG may be cropped.

CSS
<style>
  div {
    height: 160px;
    border: 1px solid #ccc;
    background: linear-gradient(135deg, #2563eb, #7c3aed);
    mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='120' height='80'><ellipse cx='60' cy='40' rx='56' ry='36' fill='%23000'/></svg>");
    mask-repeat: no-repeat;
    mask-position: center;
    mask-size: cover;
  }
</style>

<div></div>
Try It Yourself

How It Works

  1. Load a mask with a real size. The SVG is 120×80, so it has an aspect ratio. That ratio is what cover protects.
  2. Give the box a height. Without a visible area, you cannot see scaling. The gradient is what shows through opaque mask pixels.
  3. Scale until the box is full. cover grows the mask until both width and height cover the element. Extra parts are cropped.
  4. Center the crop. mask-position: center chooses which part stays visible. no-repeat keeps a single copy.

Example 2 — contain

Fit the whole mask inside the box. Empty bands stay fully masked away.

CSS
<style>
  div {
    height: 160px;
    border: 1px solid #ccc;
    background: linear-gradient(135deg, #2563eb, #7c3aed);
    mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='120' height='80'><ellipse cx='60' cy='40' rx='56' ry='36' fill='%23000'/></svg>");
    mask-repeat: no-repeat;
    mask-position: center;
    mask-size: contain;
  }
</style>

<div></div>
Try It Yourself

How It Works

  1. Same mask, different keyword. Only contain changes from Example 1.
  2. Fit without cropping. The mask grows until one side hits the box edge. The other side may leave a gap.
  3. Gaps stay hidden. Transparent mask pixels hide the gradient in those leftover bands.
  4. Stop tiling. Without no-repeat, a contained mask that is smaller than the box would tile by default.

Example 3 — Explicit Lengths

Set width and height yourself. The aspect ratio is not protected unless you pick matching numbers.

CSS
<style>
  div {
    height: 160px;
    border: 1px solid #ccc;
    background: linear-gradient(135deg, #2563eb, #7c3aed);
    mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='120' height='80'><ellipse cx='60' cy='40' rx='56' ry='36' fill='%23000'/></svg>");
    mask-repeat: no-repeat;
    mask-position: center;
    mask-size: 100px 60px;
  }
</style>

<div></div>
Try It Yourself

How It Works

  1. Two values mean width then height. 100px 60px draws the mask at exactly that size.
  2. One value would set only the width. 100px alone keeps height as auto and preserves the ratio when the mask has one.
  3. Percentages use the positioning area. 50% is half the width of the area from mask-origin, not half of the SVG file.
  4. Negative sizes are invalid. The browser ignores a negative length or percentage.

Edge Cases & Pitfalls

If the mask looks tiled, stretched wrong, or unchanged, one of these is usually why.

image

No mask-image, no scaling

mask-size only sizes an active mask layer. Set mask-image first, or use the mask shorthand that includes one.

repeat

contain can tile by default

If the scaled mask is smaller than the box, mask-repeat starts at repeat and fills the gaps with copies. Use no-repeat for a single silhouette.

gradient

Gradients have no natural size

CSS gradients have no intrinsic dimensions. With auto, they often fill the positioning area, so cover and contain can look the same. Use a file or SVG with width and height to study the keywords.

crop

cover always may crop

When the box ratio differs from the mask ratio, edges are cut off. Keep important shape detail near the center, or switch to contain.

shorthand

The mask shorthand resets size

A later mask declaration that omits size resets mask-size to auto for that layer. Set size after the shorthand, or include it in the shorthand.

Compatibility

Browser Support

mask-size is a browser painting property for CSS masking. Node.js, Deno, and Bun do not apply it. Unprefixed support is Baseline. Older WebKit used -webkit-mask-size.

✓ Baseline · Widely available since Dec 2023

mask-size

Unprefixed: Chrome 120+, Edge 120+, Firefox 53+, Safari 15.4+. Prefixed WebKit support is older. Internet Explorer has no CSS mask-size.

97% Modern browser support
Google Chrome 120+ unprefixed · older with -webkit-
Full support
Mozilla Firefox 53+
Full support
Apple Safari 15.4+ unprefixed · older with -webkit-
Full support
Microsoft Edge 120+ unprefixed
Full support
Opera 106+ unprefixed
Full support
Samsung Internet 25+ unprefixed
Full support
Internet Explorer No support
None
mask-size Widely supported

Bottom line: Safe for current browsers with the unprefixed property. Add -webkit-mask-size only if you must support older Safari or Chromium builds before the Baseline versions above. Prefer a mask with intrinsic size when teaching or testing cover vs contain. Do not treat this as a Node.js or other runtime feature.

Remember

Key Takeaways

  • Role: set how large the mask image is drawn inside the box.
  • Keywords: cover fills (may crop); contain fits (may leave gaps); auto is the default.
  • Two values: width then height. One value sets width; height becomes auto.
  • Pair with: no-repeat and often center for logos and cutouts.

One line: mask-size answers “how big is this mask image inside the box?”

Frequently Asked Questions

It sets the width and height of a mask image. You can keep the natural size, stretch with lengths or percentages, or use cover and contain to fit the box while keeping the aspect ratio.
auto, which is the same as auto auto. A mask with intrinsic size keeps that size. The property is not inherited.
cover scales up until the box is filled and may crop edges. contain scales until the whole mask fits and may leave empty bands. Both keep the aspect ratio.
The default mask-repeat is repeat. If the scaled mask is smaller than the box, it tiles. Pair contain (or a length size) with mask-repeat: no-repeat when you want one copy.
No. There must be a mask-image (or a mask shorthand that sets one). Without a mask layer, changing mask-size has nothing to scale.
Unprefixed mask-size is Baseline and widely available since December 2023: Chrome 120+, Edge 120+, Firefox 53+, Safari 15.4+. Older WebKit browsers used -webkit-mask-size. Internet Explorer does not support it. This is a browser CSS property. Node.js, Deno, and Bun do not paint it.

Next: max-block-size

Learn the maximum size of a block along the block axis.

max-block-size tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

CSS mask-repeat Property CSS max-block-size Property