The mask-border-width property is used to scale the mask border image slices created by the mask-border-slice property.
The mask border width will tell the browser how wide each border side is so that it can scale the mask border image to fit in it.
The area to which the mask border image is to be applied is called the mask border image area. By default, the boundaries of the mask border image area correspond to the boundaries of the element’s border box. (However, the boundaries of the mask border image area can be extended using the mask-border-outset property.)
The mask-border-width is specified as a list of offsets from the boundaries of the mask border image area.
The mask-border-width property can take four, three, two, or one offset values.
When four values are specified, they set the offsets on the top, right, bottom and left sides in that order. If three values are specified, the first one specifies the top offset, the second one specifies the right and left offsets, and the third one specifies the bottom offset. If two values are specified, the first one specifies the top and bottom offsets, and the second one specifies the right and left offsets. If one value is specified, it specifies all the four offsets.
If two opposite mask-border-width offsets are large enough that they overlap, then the used values of all mask-border-width offsets are proportionally reduced until they no longer overlap.
The offsets specified by the mask-border-width property are then used to scale the slices of the border image obtained from the mask-border-slice property.
The top and bottom edge (Edge 1 and Edge 3) are scaled so that their height matches the top and bottom offsets of the mask-border-width, and their width is scaled proportionally. The right and left edges (Edge 2 and Edge 4) are scaled so that their width matches that specified by the right and left offsets of the mask-border-width, and their height is scaled proportionally.
The width of the top and bottom edges, and the height of the right and left edges then rescaled in a next step based on the value of the mask-border-repeat property. You can read more about how these properties work together in the mask-border shorthand property entry.
The height and width of the mask border image corners (corners 1 through 4 in the above image) is determined by scaling the corners to the offsets of the edges that they are part of. For example, the top right corner slice, will be scaled so that its width matches the right offset of the mask-border-width and its height matches the top offset provided by the mask-border-width property.
As for the middle slice of the border image, is it either discarded or preserved, depending on whether the fill value is present in the mask-border-slice property. If it is preserved, its width is scaled by the same factor as the top image edge unless that factor is zero or infinity, in which case the scaling factor of the bottom is substituted, and failing that, the width is not scaled. The height of the middle image is scaled by the same factor as the left image edge unless that factor is zero or infinity, in which case the scaling factor of the right image is substituted, and failing that, the height is not scaled.
Trivia & Notes
We suggest you check the mask-border shorthand property entry for an explanation of the steps used to apply a mask border image to an element using the different mask border properties.
Official Syntax
-
Syntax:
mask-border-width: [<length> | <number> | <percentage> | auto]{1,4}
- Initial: auto
- Applies To: All elements. In SVG, it applies to container elements excluding the <defs> element and all graphics elements
- Animatable: no
Values
The informal syntax looks something like this:
mask-border-width = [offset] [offset]? [offset]? [offset]?
The question mark (?) indicates that the value is optional. When one offset is specified, it is used as a top, right, bottom, and left offset. When two offsets are specified, the first one represents the top and bottom offsets and the second one represents the right and left offsets. When three offsets are specified, the first represents the offset from the top, the second one represents the offset from the right and left, and the third one represents the bottom offset. When four offsets are specified, they represent the top, right, bottom, and left offsets, in that order.
These offsets can be specified as <length>, <number>, or <percentage> values. Negative offset values are not allowed for any of the mask-border-width values.
- <length>
-
See the
<length>entry for a list of possible values. - <percentage>
- Percentages refer to the size of the mask border image area: the width of the area for horizontal offsets, the height for vertical offsets.
- <number>
-
A
<number>value represents multiples of the corresponding computedborder-widthof the element. - auto
-
If
autois specified then the mask border image width is the intrinsic width or height (whichever is applicable) of the corresponding image slice (seemask-border-slice). If the image does not have the required intrinsic dimension then the correspondingborder-widthis used instead.So,
autoleaves it up to the browser to determine the mask border image width depending on whether the image slices have an intrinsic width or not. If they don’t have an intrinsic width, the value of theborder-widthis used.
Notes
The mask-border-width can also inherit its values from the computed values of the element’s parent, using the inherit keyword.
For SVG elements without an associated layout box the border-width is considered to be zero.
Examples
The following are valid mask-border-width declarations:
mask-border-width: 30px; /* one-value syntax, all offsets will be equal to 30px */
mask-border-width: 10% 30%; /* two-value syntax, top and bottom offsets = 10%, right and left offsets = 20% */
mask-border-width: auto; /* specify offset based on the slice intrinsic width */
mask-border-width: auto 30px;
mask-border-width: 10px 20px 30px 25px;
mask-border-width: 4; /* mask border image width is 4 times the width of the border specified using the boder-width property */
Live Demo
The border image used is the following:
It is 81px in width and 81px in height. Each rhombus is 27px in width and 27px in height. The border image width is set to 27px as well, so the image slices’ proportions are not scaled or changed. Play with the value of the mask-border-width property to see how that affects the scale of the image parts.
Note that the demo currently (June, 2014) does not work in any browser. It may be useful to check out the demo from the border-image-width entry. The way the border mask image is applied is similar to the way a border-image-width is applied, except that the mask image is used to mask parts of the element. The process of setting the images is the same, so checking that entry may be useful for more insight and to better know what to expect from this property.
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.
