mask-border

The mask-border property is used to apply a border mask image to an element.

It is a shorthand property used to set the longhand properties mask-border-source, mask-border-mode, mask-border-slice, mask-border-width, mask-border-outset, and mask-border-repeat.

For a detailed description of what each property does, please refer to the property’s entry.

When a mask border image is to be set on an element, it is set in several steps.

First, the image specified in the mask-border-source property is sliced into nine images—four corner images, four edge images, and one middle image—using the mask-border-slice property.

The resulting nine images are then scaled, positioned, and tiled into their corresponding mask border image regions in the following steps:

1. The images are scaled according to the value specified using the mask-border-width property.

   The top and bottom edge images are scaled vertically to fit the corresponding specified width offsets.

   The right and bottom left are scaled vertically to fit the corresponding specified right and left width offsets.

   The corner images are scaled to fit the width specified on the edges that they are a part of.

   And the middle image’s width is scaled by the same factor as the top image 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 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.

2. The images are scaled according to the value specified using the mask-border-repeat property.

   If the first keyword of the mask-border-repeat property is stretch, the top and bottom edge images and the middle image are stretched to fit the width of the border image area. Their height is not scaled.

   If the first keyword is round, the top, middle and bottom images are resized in width, so that exactly a whole number of them fit in the middle part of the mask-border-image area.

   If the first keyword is repeat or space, the top, middle, and bottom images are not scaled anymore, so their height would only be scaled from the first step above.

   If the second keyword is stretch, round, repeat, or space, the same scaling is applied to the respective left, middle, and right images, affecting the height of the images; their width is not scaled except from the first step.

3. Now that the images are scaled, they are positioned. Positioning the images is also related to the mask-border-repeat property.

   If the first keyword is repeat, the top, middle, and bottom images are centered horizontally in their respective areas. Otherwise the images are placed at the left edge of their respective parts of the mask-border-image area.

   If the second keyword is repeat, the left, middle, and right images are centered vertically in their respective areas. Otherwise the images are placed at the top edge of their respective parts of the mask-border-image area.

4. After the images have been scaled and positioned, they are tiled (repeated) as many times as necessary depending on the value of the mask-border-repeat property, to fill their respective areas.

   If the value is repeat, the images are repeated as much as necessary to fill their respective areas. If the value is space, any partial tiles are discarded and the extra space is distributed before, after, and between the tiles. (I.e. the gap before the first tile, the gap after the last tile, and the gaps between tiles are equalized.)

The mask border image can be extended outside the border area of the element using the mask-border-outset property. Refer to the property’s entry for details.

The result of the above steps can be best understood when seen visually. So it is best if you use an interactive tool to see how the different values change the rendering of the mask border image. Since the steps and procedure for applying a mask border image to an element is the same as applying a border image to it, it might help if you have a look at demos and/or interactive tools explaining the latter; that will help provide you with more insight and better understanding of how this works. The following are two great tools to do just that:

• Border Image Generator—Interactive Demo and Tool by Kevin Decker
• Grokking CSS3 border-image—Interactive Demo by Nora Brown

Trivia & Notes

The mask shorthand resets the properties mask-border, mask-border-source, mask-border-mode, mask-border-slice, mask-border-width, mask-border-outset and mask-border-repeat.