CSS mask-origin A Comprehensive Guide

Introduction to CSS mask-origin

The mask-origin property in CSS defines where a mask image is positioned within an element. Introduced in December 2023, it’s widely supported in the latest browsers but may not work on older ones.

mask-origin specifies the mask positioning area for elements rendered as a single box. It determines the origin position of an image specified by the mask-image property. For multi-box elements, it specifies which boxes the box-decoration-break property operates on to determine the mask positioning area.

By using mask-origin, developers can enhance designs with precise masking effects, ensuring elements are displayed exactly as intended.

Specification

The mask-origin property is defined in the CSS Masking Module Level 1 specification. This module details how masking properties interact with other CSS properties to create complex visual effects.

• CSS Masking Module Level 1: Details the behavior and usage of masking properties.

For more information, check the official specification:

• CSS Masking Module Level 1 - mask-origin

Description

The mask-origin property sets the origin of a mask, controlling where the mask image is positioned within an element’s box model. For single-box elements, it specifies the mask positioning area. For multi-box elements, it specifies which boxes the box-decoration-break property acts upon.

By using mask-origin, developers can precisely control the positioning of mask images, creating sophisticated and visually appealing designs.

Syntax

The mask-origin property is set using keyword values that define the positioning area of the mask image. The syntax is straightforward and allows for multiple values separated by commas.

mask-origin: keyword-value;
mask-origin: keyword-value, keyword-value;

Keyword Values

• content-box: Relative to the content box.
• padding-box: Relative to the padding box.
• border-box: Relative to the border box.
• fill-box: Relative to the object bounding box (used in SVG).
• stroke-box: Relative to the stroke bounding box (used in SVG).
• view-box: Uses the nearest SVG viewport as the reference box.

Non-Standard Values

For compatibility with older browsers:

• -webkit-mask-origin: content: Same as content-box.
• -webkit-mask-origin: padding: Same as padding-box.
• -webkit-mask-origin: border: Same as border-box.

Global Values

• inherit: Inherits the value from the parent element.
• initial: Sets the property to its initial value (border-box).
• revert: Reverts the property to its default value.
• revert-layer: Reverts the property to its default value for the current layer.
• unset: Resets the property to its inherited value if it inherits, or to its initial value if not.

Examples

/* Single value */
mask-origin: content-box;
mask-origin: padding-box;
mask-origin: border-box;

/* Multiple values */
mask-origin: padding-box, content-box;
mask-origin: view-box, fill-box, border-box;

/* Non-standard values */
-webkit-mask-origin: content;
-webkit-mask-origin: padding;
-webkit-mask-origin: border;

/* Global values */
mask-origin: inherit;
mask-origin: initial;
mask-origin: revert;
mask-origin: revert-layer;
mask-origin: unset;

Values

The mask-origin property accepts several keyword values that define the positioning area of the mask image.

content-box

• Description: Relative to the content box.
• Usage: Positions the mask image within the content area, excluding padding, border, and margin.

padding-box

• Description: Relative to the padding box.
• Usage: Positions the mask image within the content area plus padding, excluding border and margin.

border-box

• Description: Relative to the border box.
• Usage: Positions the mask image within the entire box, including content area, padding, and border, excluding margin.

fill-box

• Description: Relative to the object bounding box.
• Usage: Used in SVG, positions the mask image within the bounding box of the SVG object.

stroke-box

• Description: Relative to the stroke bounding box.
• Usage: Used in SVG, positions the mask image within the stroke bounding box of the SVG object.

view-box

• Description: Uses the nearest SVG viewport as the reference box.
• Usage: Aligns the mask image with the SVG viewport, ensuring it scales correctly with the SVG content.

Non-Standard Values

For compatibility with older browsers:

• content: Same as content-box.
• padding: Same as padding-box.
• border: Same as border-box.

Global Values

• inherit: Inherits the value from the parent element.
• initial: Sets the property to its initial value (border-box).
• revert: Reverts the property to its default value.
• revert-layer: Reverts the property to its default value for the current layer.
• unset: Resets the property to its inherited value if it inherits, or to its initial value if not.

Formal Definition

The mask-origin property is formally defined with specific characteristics guiding its usage and behavior.

Initial Value

• Initial Value: border-box

Applies To

• Applies To: All elements. In SVG, it applies to container elements excluding the <defs> element and all graphics elements.

Inherited

• Inherited: No

Computed Value

• Computed Value: As specified

Animation Type

• Animation Type: Discrete

Formal Syntax

The formal syntax for the mask-origin property is defined using specific grammar rules.

mask-origin = <coord-box>#

<coord-box> = <paint-box> | view-box

<paint-box> = <visual-box> | fill-box | stroke-box

<visual-box> = content-box | padding-box | border-box

Explanation

• <coord-box>: Represents the coordinate box, which can be any of the paint boxes or the view box.
• <paint-box>: Represents the painting box, which can be a visual box, fill box, or stroke box.
• <visual-box>: Represents the visual box, which can be content-box, padding-box, or border-box.

Example: Setting Mask Origin

1. Setting mask-origin to border-box

In this example, the mask image covers the entire element, including the content area, padding, and border.

<!DOCTYPE html>
<html>
<head>
    <style>
        .box {
            width: 22%;
            height: 200px;
            background: green;
            border: 10px solid red;
            padding: 10px;
            color: white;
            -webkit-mask-image: url("image.svg");
            -webkit-mask-repeat: repeat;
            mask-origin: border-box;
        }
    </style>
</head>
<body>
    <div class="box"></div>
</body>
</html>

2. Setting mask-origin to content-box

In this example, the mask image only covers the content area, excluding the padding and border.

<!DOCTYPE html>
<html>
<head>
    <style>
        .box {
            width: 22%;
            height: 200px;
            background: green;
            border: 10px solid red;
            padding: 10px;
            color: white;
            -webkit-mask-image: url("image.svg");
            -webkit-mask-repeat: repeat;
            mask-origin: content-box;
        }
    </style>
</head>
<body>
    <div class="box"></div>
</body>
</html>

3. Using Multiple Values

This example shows how to use multiple values to set the mask origin for different elements.

<!DOCTYPE html>
<html>
<head>
    <style>
        .box1 {
            width: 200px;
            height: 200px;
            background: blue;
            border: 10px solid yellow;
            padding: 20px;
            -webkit-mask-image: url("mask1.svg");
            -webkit-mask-repeat: no-repeat;
            mask-origin: padding-box;
        }

        .box2 {
            width: 200px;
            height: 200px;
            background: purple;
            border: 10px solid green;
            padding: 20px;
            -webkit-mask-image: url("mask2.svg");
            -webkit-mask-repeat: no-repeat;
            mask-origin: border-box;
        }
    </style>
</head>
<body>
    <div class="box1"></div>
    <div class="box2"></div>
</body>
</html>

Experimenting with Different Values

Try updating the mask-origin property to see different effects:

/* Update the mask-origin property to see different effects */
mask-origin: content-box;
mask-origin: padding-box;
mask-origin: border-box;
mask-origin: fill-box;
mask-origin: stroke-box;
mask-origin: view-box;

Specifications

The mask-origin property is defined in the CSS Masking Module Level 1 specification. For more details, refer to the official specification document:

• CSS Masking Module Level 1 - mask-origin

Browser Compatibility

The mask-origin property is widely supported across modern browsers. Here’s a summary of the browser compatibility:

• Google Chrome: Fully supported.
• Mozilla Firefox: Fully supported.
• Microsoft Edge: Fully supported.
• Safari: Fully supported.
• Opera: Fully supported.

Ensuring Compatibility

To ensure compatibility across all browsers, consider using vendor prefixes and testing your designs thoroughly.

Resources

For further exploration, check out these resources:

• Clipping and Masking in CSS: Clipping and Masking in CSS
• CSS Masking Module Level 1 Specification: CSS Masking Module Level 1
• MDN Web Docs on mask-origin: MDN Web Docs - mask-origin
• Can I Use - mask-origin: Can I Use - mask-origin

These resources will help you gain a deeper understanding of CSS masking and ensure your designs are compatible and accessible.