mask-position | CSS-Tricks

CSS Almanac → Properties → M → mask-position

Mojtaba Seyedi on Oct 12, 2020 (Updated on May 10, 2021)

In CSS, the mask-position property specifies the initial position of a mask layer image relative to the mask position area. It works like the background-position property.

.element {
  mask-image: url("star.svg");
  mask-position: 20px center;
}

Masking allows you to display selected parts of an element while hiding the rest. In the following demo, you can change the position of the mask layer image:

Syntax

mask-position: <position> = [ [ left | center | right ] || [ top | center | bottom ] | [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]? | [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ] ]

Initial value: 0% 0%
Applies to: all elements. In SVG, it applies to container elements excluding the <defs> element, all graphic elements and the <use> element.
Inherited: no
Computed value: consisting of: two keywords representing the origin and two offsets from that origin, each given as an absolute length (if given a <length>), otherwise as a percentage.
Animation type: repeatable list

Values

A <position> can be specified in terms of offset keywords (top, left, bottom, right, and center), percentages, and length values regarding the edges of the element, similar to the CSS background-position property.

/* Offset keywords */
mask-position: top;
mask-position: right;
mask-position: bottom;
mask-position: left;
mask-position: center;
 
/* Length values */
mask-position: 100px 200px;
mask-position: 5rem 20%;
mask-position: 0 10vh;
 
/* Percentage values */
mask-position: 25% 50%;
 
/* Global values */
mask-position: intial;
mask-position: inherit;
mask-position: unset;

Value definitions

<length>: Any valid CSS length (such as px, em, rem and %, among others) which will specify how far the edge of the mask image is from the corresponding edge of the element.
<percentage>: Specifies the position of mask layer image as a percentage value relative to the mask positioning area minus size of the mask image.
top: Equivalent to 0% for the vertical position.
right: Equivalent to 100% for the horizontal position.
bottom: Equivalent to 100% for the vertical position.
left: Equivalent to 0% for the horizontal position.
center: Equivalent to 50% for the horizontal position if the horizontal position is not otherwise specified, or 50% for the vertical position, if it is.
initial: Applies the property’s default setting, which is 0% 0%.
inherit: Adopts the mask-position value of the parent.
unset: Removes the current mask-position from the element.

Using multiple values

This property can take a comma-separated list of values for mask positions and each value is applied to a corresponding mask layer image specified in the mask-image property. In the following example, the first value specifies the position of the first image, the second value specifies the position of the second image, and so on.

.element {
  mask-image: url("image-1.png"), url("image-2.png"), url("image-3.png");
  mask-position: 100px 10%, 0 right, center;
}

Different syntax

mask-position can take one, two, three or four values to specify the position of the mask layer horizontally and vertically.

Single value

In case a single value is set, that is taken as the horizontal value and the vertical value is assumed to be center.

mask-position: 100px; /* 100px center */

Two values

In case of using pair values, the first one is taken as the horizontal value, and the second one specifies the position of the make layer vertically.

mask-position: 10% 50%; /* x=10%, Y=50% */

If both values are keywords, then the order of the keywords is irrelevant:

mask-position: top left; /* = left top */

But when we have a combination of keyword and length or percentage, the order matters and the first value always corresponds to the horizontal offset. Therefore:

mask-position: 50% right; /* = horizontal center, vertical right */
mask-position: right 50%; /* = horizontal right, vertical center */

Three values

If three values are given, the missing offset is assumed to be zero:

mask-position: left 100px bottom; /* left=100px bottom=0 */

Four values

A four-value syntax allows you to specify which sides of the element you are positioning the mask relative to (values 1 and 3), and then the distance away from those sides (values 2 and 4).

So, if you want to position the mask 100px from the bottom of the element, and 200px from the right, you can do like the following:

mask-position: bottom 100px right 200px;

Animating masks

It’s possible to animate mask-position and mask-size using keyframe animation and CSS transitioning, like the following:

.element {
  mask-image: url("mask.png");
  mask-position: 10px 10px;
  transition: mask-position 1s ease-in-out;
}
 
.element:hover {
  mask-position: right 10px bottom 10px;
}

In this next demo, we are animating position of the mask layer using keyframe animation: