Border images

Article
11/05/2015

Internet Explorer 11 supports defining custom border images with the border-image property from the CSS Backgrounds and Borders Module Level 3 W3C specification. Using the border-image property, you can specify your own images for borders as an alternative to traditional border styles.

The border-image property

The border-image property is a shorthand property which specifies how an image is used in place of border styles. The border-image shorthand is made up of five separate properties. You can use the separate properties to specify each component of a CSS border image, but in many cases it’s more convenient to set them in one place using this shorthand property. The syntax for the border-image property is as follows:

border-image: <border-image-source> || <border-image-slice> [ / <border-image-width> | / <border-image-width> ? /<border-image-outset> ] ? || <border-image-repeat>

Property	Description
border-image-source	Specifies the location of the image to be used for the border.
border-image-slice	Using four inward offsets, this property slices the specified border image into a three by three grid: four corners, four edges, and a center.
border-image-width	Specifies the width/height of the border image by defining inward offsets from the edges of the border image area.
border-image-outset	Specifies the amount by which the border image area extends beyond the border box.
border-image-repeat	Specifies if the sides of the border image are scaled or tiled.

Defining, slicing, and repeating the image

When using border-image, you have to first specify border style values. Below is a div element with a solid black, 15 pixel-wide border. The black area is the border box, or border area. This is where the border image will be confined to by default. This can be adjusted by specifying values for border-image-width and border-image-outset.

The picture below (with a transparent background) is an 81 x 81 pixel image used for the border image in the following example.

After styling the element with border-image properties, the original border styles are overridden and the sliced-up border image will fill the border box. The styles below are used to define border image styles on an HTML element and it looks like the following image.

#box { 
   border: solid 15px;
   border-image: url("border.png") 27 27 round stretch;
}

In the above CSS, the numbers following the image source define slicing distances for the image (border-image-slice). The slicing distances are set at 27 pixels from the top, right, bottom, and left of the image. These slicing distances are visible in red in the illustration below.

"Round" and "stretch" refer to how the images fill the area between the border (border-image-repeat). The first value, round, is applied to the horizontal sides. The image is tiled, or repeated, until it fills the area between the edges of the border. If the area cannot be filled with a whole number of tiles, the image is rescaled so that a whole number of tiles will fill the area. The second value, stretch, is applied to the vertical sides. Here, the image is stretched to fill the area between the edges of the border. Stretch is the default value.

The example below again uses the shorthand border-image property to manipulate the same image as above into a very different looking border.

#box {
   border: solid 15px;
   border-image: url("border.png") 20 15 round; 
}

In this example, slicing distances are set at 20 pixels from the top and bottom of the image and 15 pixels from the left and right of the image. For this example, instead of using the default border-image-repeat, round is used.

Specifying width and outset values

You can also specify the width and the height of the border image by defining inward offsets from the edges of the border image area using the border-image-width property. Border-image-width has a default value of one. This means the border-image-width is one multiple of the computed value of border-width, or the width of the border box. The example above shows a div element with a border-image-width of 1 giving its border image a 15px width, (1 x the border-width value of 15px). Using the same CSS as above, if you set the border-image-width to 20px, it will look like the image below. In this example, you are defining an inward offset of 20px from the edges of the border image area.

The CSS for the above div element looks like the following:

#box {
   border: solid 15px;
   border-image: url("border.png") 20 15 /20px round;
}

You can further manipulate the image by specifying the amount by which the border image area extends beyond the border box using the border-image-outset property. Setting border-image-outset values to 0px from the top, 30px from the right, 30px from the bottom, and 10px from the left will result in the following image.

The CSS for the above div element looks like the following:

#box {
   border: solid 15px;
   border-image: url("border.png") 20 15 /20px /0px 30px 30px 0px round;
}

API reference

borderImage

Specification

CSS Backgrounds and Borders Module Level 3, Section 6

Share via