CSS Reference Property

mask-repeat

The mask-repeat property is used to specify whether or not and how a mask layer image is repeated (or tiled). Repeating a mask layer image happens after it has been sized and positioned.

An mask layer image can be repeated vertically, horizontally, both vertically and horizontally, or it can be set not to repeat at all.

If a mask layer image is repeated, it may happen that some of its tiles get clipped if they don’t fit a whole number of times into the mask positioning area of the element. Prior to CSS3, there was nothing a developer could do to prevent that. But in the backgrounds and borders module level 3, two new values have been introduced that allow developers to prevent the image clipping by either rescaling that image so that it fits a whole number of times, or repeating the image as often as it will fit within the area without being clipped, and then spacing the images out to fill the area. The same values introduced for the background-repeat property can be used for the mask-repeat property, too.

The property can take either a single value or two keyword values. The values specify whether and how the image is repeated horizontally and vertically.

If one single value is used, the value is considered a shorthand for the two-value syntax and the other value is set by the browser (see values section below). If two keyword values are used, the first one is for the horizontal direction, the second for the vertical one.

Trivia & Notes

The mask-repeat property works and has the same values as the background-repeat, except that the latter’s initial value is repeat, while the mask-repeat‘s initial value is no-repeat.

Official Syntax

  • Syntax:

    mask-repeat: <repeat-style>#
    
    /* where */
    
    <repeat-style> = repeat-x | repeat-y | [repeat | space | round | no-repeat]{1,2}
                           
  • Initial: no-repeat
  • Applies To: All elements. In SVG, it applies to container elements excluding the <defs> element and all graphics elements
  • Animatable: no

Notes

The hash tag (#) indicates that the property takes any number values. The list of mask-repeat values is comma-separated.

When the mask-repeat property takes a list of comma-separated values, each value is applied to a corresponding mask layer image specified in the mask-image property (first value for the first image, second value for the second image, and so on).

Values

repeat-x
Can be used as a single value and is equivalent to repeat no-repeat. The mask layer image is repeated horizontally but not vertically.
repeat-y
Can be used as a single value and is equivalent to no-repeat repeat. The mask layer image is repeated vertically but not horizontally.
repeat
Can be used as a single value and is equivalent to repeat repeat. The mask layer image is repeated both horizontally and vertically.
space
Can be used as a single value and is equivalent to space space. Spacing is added between repeated mask images on the horizontal axis as well as on the vertical axis.
round
Can be used as a single value and is equivalent to round round.
no-repeat
Can be used as a single value and is equivalent to no-repeat no-repeat. The mask layer image is not repeated at all. This is the default value.
repeat
The mask layer image is repeated in the specified direction as often as needed to cover the mask painting area. If the image does not fit a whole number of times in the element, the last image may get clipped.
space
The mask layer image is repeated as often as will fit within the mask positioning area without being clipped. And then the remaining space in the specified direction is distributed between the mask images that are spaced out to fill the area. The first and last images touch the edges of the area. The value of mask-position for this direction is ignored, unless the image is bigger than the mask area and there is not enough space for two copies of the image in this direction, in which case only one image is placed and mask-position then determines its position in this direction.
round
The mask layer image is repeated as often as will fit within the mask positioning area. If it doesn’t fit a whole number of times, it is rescaled in the specified direction so that it does.
no-repeat
The mask layer image is not repeated in the specified direction. It is only drawn once onto the mask positioning area. The position of the mask in that area (where it should appear) is specified by the mask-position property.

Examples

The following example sets two mask layer images and then sets their mask-repeat values:

.el {
    mask-image: url(my-mask.png), linear-gradient(black, white);
    mask-repeat: no-repeat, repeat-x;
}
                

The following example will repeat a mask image only vertically, at the center of an element (forming like a vertical column at the center). First, the image is positioned at the center using the mask-position property, and then it is set to repeat vertically using repeat-y, so it is repeated above and below the center position.

.element {
    mask-image: url(some/image.png);
    mask-position: center center;
    mask-repeat: repeat-y;
}
                

The following image shows the effect of space on repeating the background image on an element.

mask-repeat-space
The effect of space: the mask layer image of a dot is tiled to cover the whole mask painting area and the mask layer images are equally spaced.

Live Demo

The mask layer image is set to be repeated horizontally in the following demo after positioning it at the center of the element. Try changing the value of the mask-repeat property (and the element itself if you want) to see how the mask is tiled differently.

View this demo on the Codrops Playground

Browser Support

CSS Masks

Method of displaying part of an element, using a selected image as a mask

W3C Candidate Recommendation

Supported from the following versions:

Desktop

  • 4*
  • 3.5
  • No
  • 15*
  • 4*

Mobile / Tablet

  • 3.2*
  • 2.1*
  • 37*
  • 56*
  • 51

* denotes prefix required.

  • Supported:
  • Yes
  • No
  • Partially
  • Polyfill

Stats from caniuse.com

Notes

This module, as you can see in the support table above, hasn’t been fully implemented in all browsers, so you’re probably not going to be able to use all features even in browsers that have implemented certain properties (for the time being).

In the meantime, you can check out this open source feature support table by Alan Greenblatt on GitHub. The purpose of this table is to provide some insight into what the current state of affairs is with various browser implementations of CSS Clipping and Masking features.

Further Reading

Written by

Last updated December 11, 2016 at 10:38 pm by Mary Lou

Do you have a suggestion, question or want to contribute? Submit an issue.