Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Filters, Masks and Shapes

The mask-position property

Reference for the CSS mask-position property: place a mask image inside the element with keywords, lengths and percentages, plus animation tips.

The mask-position property sets where each mask layer is placed inside its positioning area (by default the border box). It works exactly like background-position: keywords, lengths and percentages, with one or two (or up to four) values.

Positioning matters when the mask does not cover the whole element, for example a single shape that is no-repeat. Because mask-position can be animated, it is also a way to move a gradient "spotlight" or shimmer across an element.

CSS
.window {
  mask-image: radial-gradient(circle, #000 40px, transparent 41px);
  mask-repeat: no-repeat;
  mask-position: 30px 20px;
}

Try it

Moving the visible window
Animating the position for a shimmer

Syntax

CSS
mask-position: <position>#

/* <position> = [ left | center | right | <length-percentage> ]
              | [ 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, container elements (except <defs>) and graphics elements
  • Inherited: no
  • Animatable: yes (as a repeatable list of positions)
  • Computed value: as for background-position: a list of keyword/offset pairs with lengths made absolute

Values

Value Description
left, center, right, top, bottom Keywords for edges and the middle. One keyword assumes center for the other axis.
<length> An offset from the top-left corner of the positioning area.
<percentage> Aligns that percentage point of the mask with the same point of the area, so 50% centers and 100% aligns to the far edge.
Four-value syntax Offsets from chosen edges, e.g. right 10px bottom 20px.

Usage notes

  • Percentages align points, not just offsets. mask-position: 100% 0 places the mask's right edge against the area's right edge, not outside it.
  • Only visible with a smaller mask. If the mask is auto-sized and covers the whole element and repeats, position only shifts the tiling pattern.
  • Mind the edges. If mask-repeat is no-repeat, everything outside the mask is hidden. A window moved partly outside the element is cut off.
  • Animate it, not the image. Moving mask-position is cheaper than changing the gradient. Make the mask larger than the element (for example 250%) so there is room to travel.
  • Respect reduced motion for shimmer and sweep effects.
  • Mask area. The positioning area is set by mask-origin (default border-box), which differs from the usual padding-box default of backgrounds.

Browser support

Unprefixed mask-position works in current versions of the major browsers; older ones needed -webkit-mask-position.