CSS mask-position Property

Description

The mask-position property controls where a mask image is placed relative to the element it masks. Conceptually it defines the anchor point of the mask graphic so that different parts of the mask align over different parts of the element; moving the position shifts which portions of the mask overlap the element content, thereby changing what is revealed or hidden. This is the primary tool for aligning a mask image when the default placement does not produce the intended visual result.

When working with layered mask images, each layer may have its own position, so the order and placement of those positions correspond to the same ordering of the mask images defined by mask-image. That means you can independently place multiple mask layers to create complex composite effects: one layer might be centered while another is offset, producing combined transparency patterns where the layers overlap. For vector‑based or SVG masks, positioning behavior can also interact with the mask’s internal coordinate system, so the practical visual result depends on both the mask content and the position anchoring.

Positioning interacts closely with how the mask is sized and tiled. When the mask graphic is scaled or stretched by mask-size its placement changes the region of the element that receives the scaled artwork; when a mask is repeated by mask-repeat, the position defines the origin of the tiling pattern, which affects where tile seams and repetition boundaries fall relative to the element. Because of these interactions, a subtle position shift can change perceived density, alignment of pattern elements, or the placement of repeated motifs in the mask.

In practical use, mask-position is often treated like the analogous positioning used for backgrounds (see background-position) - it’s useful for fine-tuning visual alignment and for animating a mask to create reveal or sliding effects. Designers commonly adjust position to sync a mask with underlying artwork, to offset an SVG mask’s focal region, or to animate a mask across an element for transitions. Understanding how position combines with mask layering, sizing, and repetition gives you precise control over which parts of an element are visible and how complex masking compositions behave.

Definition

Initial value: 0% 0%
Applies to: all elements; In SVG, it applies to container elements excluding the <defs> element and all graphics elements
Inherited: no
Computed value: Consists of two keywords representing the origin and two offsets from that origin, each given as an absolute length (if given a ), otherwise as a percentage.
Animatable: yes
JavaScript syntax: object.style.maskPosition

Syntax

mask-position: <position>;

Values

<position>
You can define the position using keywords, lengths, or percentages.

1. Keyword Values

These define the position relative to the edges of the element.
- Horizontal: left, center, right.
- Vertical: top, center, bottom.
Note: If you only provide one keyword (e.g., mask-position: top;), the other dimension defaults to center.

2. Length Values

You can use absolute or relative units such as px, em, or rem.
- mask-position: 20px 50px; (Moves the mask 20px from the left and 50px from the top).
3. Percentage Values

Percentages are calculated based on the difference between the mask image size and the mask area size.
- 0% 0%: The top-left corner of the mask is aligned with the top-left corner of the area.
- 50% 50%: The mask is perfectly centered.
- 100% 100%: The bottom-right corner of the mask is aligned with the bottom-right corner.
4. Edge Offsets (Three or Four Values)

You can specify an offset from a specific edge:
- mask-position: right 20px bottom 10px; (20px from the right edge and 10px from the bottom edge).

Example

HTML

<div class='wrap'>

  <h2>mask-position examples</h2>

  <div class='row'>

    <figure>

      <div class='demo mask-demo pos-left'></div>

      <figcaption>mask-position: left top</figcaption>

    </figure>

    <figure>

      <div class='demo mask-demo pos-center'></div>

      <figcaption>mask-position: center</figcaption>

    </figure>

    <figure>

      <div class='demo mask-demo pos-right'></div>

      <figcaption>mask-position: right bottom</figcaption>

    </figure>

  </div>

</div>

CSS

.wrap {
  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
  padding: 24px;
}

h2 {
  margin: 0 0 12px 0;
  font-size: 18px;
}

.row {
  display: flex;
  gap: 18px;
  align-items: center;
}

figure {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
  margin: 0;
}

figcaption {
  font-size: 13px;
  color: #333;
}

.demo {
  width: 160px;
  height: 160px;
  border-radius: 12px;
  background: linear-gradient(135deg, #ff7a18, #af002d 45%, #319197);
  box-shadow: 0 6px 16px rgba(16, 24, 40, 0.12);
}

/* SVG mask embedded as a data URL; the circle reveals the underlying background */
.mask-demo {
  -webkit-mask-image: url('data:image/svg+xml;utf8,');
  -webkit-mask-repeat: no-repeat;
  -webkit-mask-size: 40%;
  -webkit-mask-position: left top;

  mask-image: url('data:image/svg+xml;utf8,');
  mask-repeat: no-repeat;
  mask-size: 40%;
  mask-position: left top;
}

/* Different mask-position values demonstrated */
.pos-left {
  -webkit-mask-position: left top;
  mask-position: left top;
}

.pos-center {
  -webkit-mask-position: center;
  mask-position: center;
}

.pos-right {
  -webkit-mask-position: right bottom;
  mask-position: right bottom;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS mask-position property. Hover over a browser icon to see the version that first introduced support for this CSS property.