Themask-positionCSS property sets the initial position, relative to the mask position layer set bymask-origin, for each defined mask image.

Syntax

/* Single <position> keyword value *//* Sets second value to 'center' */mask-position: left;mask-position: center;mask-position: right;mask-position: top;mask-position: bottom;/* Two <position> keyword values */mask-position: left center;mask-position: right top;/* One length or percentage <position> value *//* Horizontal position. Vertical position set to 'center' */mask-position: 25%;mask-position: 0px;mask-position: 8em;/* Two length or percentage <position> values *//* First value: horizontal position. Second value: vertical position */mask-position: 25% 75%;mask-position: 0px 0px;mask-position: 10% 8em;/* Edge offsets: Four <position> values */mask-position: bottom 10px right 20px;mask-position: right 3em bottom 10px;mask-position: bottom 10px right 0;/* Multiple <position> values */mask-position:  top left,  bottom 10px right 10px;mask-position:  1rem 1rem,  center;/* Global values */mask-position: inherit;mask-position: initial;mask-position: revert;mask-position: revert-layer;mask-position: unset;

Values

One or more<position> values, separated by commas.

<position>

One, two, or four values representing a 2D position specifying the edges of the element's box. Relative or absolute offsets can be given.

Description

Themask-position property defines the position of each mask layer. An element can have multiple mask layers applied. The number of layers is determined by the number of comma-separated values in themask-image property value (evennone values create a layer).

Eachmask-position value in the comma-separated list of values is matched up with an associated mask layer as defined by the list ofmask-image values, in order. If the number of values in the two properties differs:

• Ifmask-position has more values than mask-image, the excess values ofmask-position are not used.
• Ifmask-position has fewer values than mask-image, themask-position values are repeated.

Eachmask-position defines the associated mask layer's position relative to the associatedmask-origin value. Themask-origin property values are similarly matched up with themask-image values, in order, with excessmask-position values being unused ormask-position values being repeated if they are fewer in number than themask-origin values. Each mask layer, therefore, has an associatedmask-origin andmask-position value.

If nomask-origin is set, the value defaults topadding-box, meaning the origin of eachmask-position is the element'spadding-box.

One-value syntax

If only onemask-position value is specified, the second value is assumed to becenter. If the value is a<length> or<percentage>, it defines the position of the mask along the horizontal axis, with the mask being vertically centered within the origin box. For example,mask-position: 0%; is equal tomask-position: 0% center.

If you use a single keyword for positioning, the other value will resolve tocenter. The default ofmask-position is0% 0%, which equates tomask-position: top left. However:

• mask-position: top; is equivalent tomask-position: top center;.
• mask-position: left; is equivalent tomask-position: center left.
• mask-position: center; is equal tomask-position: center center.

If the value is a<length> value, it represents the horizontal position as an offset from the left edge of the mask positioning. A positive value represents an offset inward from the left edge of the box container. The position can be set outside of the element's box using a negative value — this creates an outward offset that places the item outside the container's left edge.

Percentage values

A<percentage> value represents the mask's horizontal position value relative to the width of the container, positioned relative to the left edge. However, the offset is not from the mask edge to the box edge. Instead, the mask image dimension issubtracted from the container's dimension, and then a percentage of the resulting value is used as the direct offset from the box's left edge, which is the same aspercentage values forbackground-position.

The equation is:

(container dimension - mask dimension) * position percentage = dimension offset value

Given a100px-wide mask and a1000px-wide origin box, settingmask-position: 10%; (the equivalent of10% 50%) results in the mask being vertically centered at90px from the left edge. The equation is(1000 - 100) * 10% = 90. If the left offset had been0%, the mask's left edge would be flush to the left of the container ((1000 - 100) * 0% = 0).

If the left offset had been100%, the mask's right edge would be flush to the right of the container as the left edge of the100px wide mask would be900px ((1000 - 100) * 100% = 900) from the left edge of the container (the100px mask width plus900px distance from the left edge means the right edge would be1000px from the left edge, which is the right edge of the container).

Two-value syntax

A two-value<position> specifies the position of the mask image inside its mask positioning area, with length and percentage values specifying offsets from theleft andtop of the area.

If the two values are<length> values,<percentage> values, or the keywordcenter, the first value represents the horizontal position as an offset from the left edge of the mask positioning area, and the second value represents the vertical position as an offset from it's top edge, withpercentages being offset by the mask's size in that dimension.

In addition, if<percentage> values are specified, the first value is also the horizontal position value relative to the left edge, and the second value is also the vertical position value relative to the top edge.

A pair of axis-specific keywords can be reordered, as can an axis-specific keyword and a length or percentage, but two length or percentage values are not interchangeable.If one of the two values istop,right,bottom, orleft, the order of the two values doesn't matter. Anycenter or<length-percentage> value in the pair of values will be applied to the other dimension.

Four-value syntax

The four-value syntax consists of two pairs of values, each pair containing a keyword specifying the edge to offset from, and a<length> and<percentage> value specifying the offset distance. For example,mask-position: left 1em top 2em specifies a1em horizontal offset from the left box edge and a2em vertical offset from the top edge. The two-value equivalent would bemask-position: 1em 2em.

Because we're defining the offset edges when using the four-value syntax, the order isn't important:mask-position: top 2em left 1em andmask-position: left 1em top 2em both produce the same result.

The real power of the four-value syntax is that it allows us to specify offset edges other thanleft andtop. For example,mask-position: bottom 10px right 20px creates a10px vertical offset up from the bottom edge and a20px horizontal offset leftward from the right edge. Usually, the four-value syntax is used to offset from the bottom and/or right. But this syntax is also helpful if you can't remember the offset edge order for the two-value syntax.

One thing to note is that, unlike the<bg-position> data type values forbackground-position, the<position> values formask-position do not allow for a 3-value syntax and do not allow offsetting fromcenter. When offsetting the mask from thebottom orright, themask-position requires all four values to be declared.

For the four-value syntax to be valid, it needs to specify eithertop orbottom as the vertical offset edge, along with the vertical length or percentage offset value, and eitherleft orright as the horizontal offset edge, along with the horizontal length or percentage offset value.

Formal definition

Formal syntax

mask-position =
<position>#

<position> =
<position-one>|
<position-two>|
<position-four>

<position-one> =
left|
center|
right|
top|
bottom|
x-start|
x-end|
y-start|
y-end|
block-start|
block-end|
inline-start|
inline-end|
<length-percentage>

<position-two> =
[left|center|right|x-start|x-end]&&[top|center|bottom|y-start|y-end]|
[left|center|right|x-start|x-end|<length-percentage>][top|center|bottom|y-start|y-end|<length-percentage>]|
[block-start|center|block-end]&&[inline-start|center|inline-end]|
[start|center|end]{2}

<position-four> =
[[left|right|x-start|x-end]<length-percentage>]&&[[top|bottom|y-start|y-end]<length-percentage>]|
[[block-start|block-end]<length-percentage>]&&[[inline-start|inline-end]<length-percentage>]|
[[start|end]<length-percentage>]{2}

<length-percentage> =
<length>|
<percentage>

Examples

Basic usage

<section>  <div></div></section>

section {  border: 1px solid black;  width: 250px;  height: 250px;}div {  width: 250px;  height: 250px;  margin-bottom: 10px;  background: blue linear-gradient(red, blue);  mask-image: url("/shared-assets/images/examples/mask-star.svg");  mask-repeat: no-repeat;  mask-position: top right;}

Specifications

Browser compatibility

See also

• background-position
• mask-image
• mask-origin
• mask-repeat
• mask-size
• mask shorthand
• mask-border
• mask-border-outset
• Introduction to CSS masking
• CSSmask properties
• Declaring multiple masks
• CSS masking module
• background-position
• <position>