CSS Mask Position: A Complete Guide

The mask-position property is a powerful CSS feature that gives you precise control over where your mask images appear within an element. Whether you're creating sophisticated visual effects, building responsive hero sections, or implementing creative brand animations, understanding mask-position is essential for modern web development.

For teams building polished user interfaces, CSS masking opens up creative possibilities that would otherwise require multiple images or complex JavaScript solutions. Combined with CSS grid layouts and modern CSS animation techniques, mask-position helps you create memorable visual experiences that perform well across all devices.

What is mask-position?

The mask-position property sets the initial position of mask images relative to the mask positioning area. It works in conjunction with mask-origin to define exactly where your mask sits within your element's box.

Key Concepts

• Sets initial position of mask images within element
• Works with mask-origin to define the positioning area
• Analogous to background-position but for mask layers
• Part of CSS Masking Level 1 specification

CSS masking uses the alpha channels of images to selectively reveal or hide parts of elements. The mask-position property controls where that mask sits relative to your element's box, enabling precise control over the reveal effect. This is particularly useful when working with custom shapes, gradient reveals, or layered visual effects that need to respond to different viewport sizes.

Understanding how mask-position interacts with other CSS properties like CSS nesting and specificity helps you write maintainable, performant stylesheets that scale with your project.

Syntax Deep Dive

The mask-position property offers flexible syntax options that mirror background-position.

Single Keyword Values

When only one value is specified, the second value defaults to 'center':

/* Single keyword - second value defaults to center */
mask-position: left; /* left center */
mask-position: right; /* right center */
mask-position: top; /* top center */
mask-position: bottom; /* bottom center */
mask-position: center; /* center center */

Two-Value Syntax

Two-value syntax specifies both horizontal and vertical positions:

/* Keyword combinations */
mask-position: left top;
mask-position: right bottom;
mask-position: center center;

/* Length values */
mask-position: 20px 30px;
mask-position: 2rem 1.5rem;

/* Percentage values */
mask-position: 50% 50%;
mask-position: 25% 75%;

Edge Offset Syntax (Four-Value)

Four-value syntax provides precise edge offsets from any edge:

/* Edge offset from right edge, 20px from bottom */
mask-position: right 20px bottom 10px;

/* Offset from left edge only */
mask-position: left 15px;

/* Multiple offsets */
mask-position: right 5% bottom 25px;

The four-value syntax is particularly powerful for creating breathing room or positioning near specific edges without calculating precise pixel or percentage values. This approach is especially useful when working with CSS container queries where elements need to adapt to their container's dimensions.

Value Types Explained

Keyword Values

Five positioning keywords control mask placement:

• left - Aligns mask to left edge, vertical defaults to center
• right - Aligns mask to right edge, vertical defaults to center
• top - Aligns mask to top edge, horizontal defaults to center
• bottom - Aligns mask to bottom edge, horizontal defaults to center
• center - Centers mask in both directions

Length and Percentage Values

Length values (px, em, rem) are absolute offsets from the positioning area edge.

Percentage behavior: Percentages calculate as (container dimension - mask dimension) × percentage = offset. For example, with a 200px container and 100px mask:

• 0% = mask starts at container left edge
• 50% = mask is centered
• 100% = mask ends at container right edge

When using percentage values, keep in mind that the calculation considers the available space after the mask size is accounted for. This is consistent with how CSS table layouts and other CSS layout properties handle percentage-based positioning.

mask-position and mask-origin Relationship

The mask-origin property defines the positioning area (border-box, padding-box, content-box, or fill-box). mask-position then positions the mask within that area.

.element {
 /* Default: positioning area is padding-box */
 mask-origin: padding-box;
 mask-position: center;
 
 /* Alternative: position relative to content only */
 mask-origin: content-box;
 mask-position: top left;
 
 /* SVG elements: use fill-box */
 mask-origin: fill-box;
 mask-position: center;
}

Note: The positioning area can be different from the clipping area (mask-clip). This distinction becomes important when you want the mask positioned relative to one area but clipped to another, which is useful for creating sophisticated visual effects that maintain consistent spacing regardless of border or padding changes.

When working with mask-origin and mask-position together, consider how these properties interact with your overall CSS data types and value system to ensure consistent behavior across your stylesheet.

Practical Examples

Example 1: Hero Section Gradient Reveal

.hero-image {
 mask-image: linear-gradient(to top, black 50%, transparent 100%);
 mask-size: 100% 200%;
 mask-position: bottom;
 mask-repeat: no-repeat;
}

.hero-image.scrolled {
 mask-position: top;
}

Creates a reveal effect that animates smoothly when scrolling.

Example 2: Multiple Mask Layers

.feature-card {
 mask-image: url('corner-accent.svg'), url('check-mark.svg');
 mask-position: top right, center left;
 mask-repeat: no-repeat;
}

Multiple mask-position values map to corresponding mask-image layers. When using multiple masks, each position corresponds to its respective mask layer in the order they were defined. This powerful technique enables composite visual effects that would otherwise require complex image editing.

Example 3: Responsive Position

.masked-graphic {
 mask-image: url('logo-mask.png');
 mask-repeat: no-repeat;
 mask-position: center;
}

@media (max-width: 768px) {
 .masked-graphic {
 mask-position: left center;
 }
}

Responsive positioning is essential for maintaining visual impact across different screen sizes. By adjusting mask-position within media queries, you ensure your masked graphics adapt appropriately to each viewport while maintaining the intended visual effect.

Troubleshooting Common Issues

Issue 1: Mask Not Appearing in Expected Position

Check: Verify mask-size is set appropriately--if the mask is larger than the positioning area, it may extend beyond visible bounds. Also verify mask-origin matches your intended positioning area. A common mistake is assuming the mask will scale automatically; you often need to set mask-size explicitly.

Issue 2: Inconsistent Behavior Across Browsers

Check: Always include both -webkit-mask-position and mask-position. Check that mask-origin is consistent, as different browsers may have different defaults. Testing across Chrome, Firefox, Safari, and Edge helps identify browser-specific quirks early in development.

Issue 3: Percentage Calculations Seem Wrong

Check: Remember that percentage values are calculated as (container - mask) × percentage. A 50% position centers the mask, but the visible portion depends on mask-size relative to container. This can be counterintuitive at first, but it ensures proportional positioning that adapts to container size changes.

For more complex debugging scenarios, consider how CSS custom properties and CSS named items can help you manage and debug mask positioning across your stylesheet.

Conclusion

The mask-position property provides the precision control you need to create sophisticated masking effects in modern web interfaces. With excellent browser support since Baseline 2023 and a syntax that mirrors the familiar background-position, it's a powerful tool that's both accessible and capable.

Start with simple center positioning, then explore edge offsets and multi-layer techniques to unlock the full potential of CSS masking. Combined with other modern CSS features like CSS grid tracks and strategic use of color in web design, mask-position helps you create polished, performant interfaces that stand out.

Sources

1. MDN Web Docs: mask-position -- Comprehensive reference with full syntax documentation and practical examples
2. Web.dev: CSS Masking -- Google-authored guide covering mask-image usage with performance considerations
3. MDN Web Docs: CSS Mask Properties -- Detailed guide explaining how mask properties work together