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-positionfor 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 andmask-positionthen 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-positionproperty.
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.
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.
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
- 120
- 53
- No
- 106
- 15
Mobile / Tablet
- 15
- 131
- No
- 131
- 132
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.
