CSS Reference Property

border-image

The border-image property is used to define an image to be used instead of the border styles given by the border-style properties and as an additional background layer for the element.

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

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

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

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

The border image sliced into nine images. The size of each of these images is determined by the values given by the border-image-slice property. They don't have to be equal in size. — The border image sliced into nine images. The size of each of these images is determined by the values given by the `border-image-slice` property. They *don’t* have to be equal in size.

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

The images are scaled according to the value specified using the border-image-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.
The images are scaled according to the value specified using the border-image-repeat property.
If the first keyword of the border-image-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 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.
Now that the images are scaled, they are positioned. Positioning the images is also related to the border-image-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 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 border-image area.
After the images have been scaled and positioned, they are tiled (repeated) as many times as necessary depending on the value of the border-image-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.)

All images are drawn at the same stacking level as normal borders: immediately in front of the background layers; so, a border image will always be on top of any background images.

The border image can be extended outside the border area of the element using the border-image-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 border image. 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

Official Syntax

Syntax:

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

Initial:
none 100% / 1 / 0 stretch , which is the concatenation of the initial values of the longhand properties
Applies To: All elements, except internal table elements when border-collapse is collapse
Animatable: no

Notes

Omitted values from the shorthand declartion are set to their default values.

Values

<‘border-image-source’>: See the border-image-source property entry for a list of possible values.
<‘border-image-slice’>: See the border-image-slice property entry for a list of possible values.
<‘border-image-width’>: See the border-image-width property entry for a list of possible values.
<‘border-image-outset’>: See the border-image-outset property entry for a list of possible values.
<‘border-image-repeat’>: See the border-image-repeat property entry for a list of possible values.

Examples

The following sets a border image on an element.

.element {
  border-image: url(path/to/image.png) 25 40 25 40 / 30 40 30 40 / 30 space;
}

A lot of authors tend to not set the outset and keep the slice size and width the same, so a lot of border-image declarations would look like the following:

.element {
    url("border.png") 27 round stretch;
}

The following two examples are borrowed from the specification.

This example creates a top and bottom border consisting of a whole number of orange diamonds and a left and right border of a single, stretched diamond. The corners are diamonds of a different color. The image to tile is as follows. Apart from the diamonds, it is transparent: border-img

The image is 81 by 81 pixels and has to be divided into 9 equal parts. The style rules could thus be as follows:

.element {
  border: double orange 1em;
  border-image: url("border.png") 27 round stretch;
 }

The result, when applied to an element of 12 by 5em, will be similar to this:

example-1-result

This shows a more complicated example, demonstrating how the border image corresponds to the fallback border-style but can also extend beyond the border area. The border image is a wavy green border with an extended corner effect. The following is the border-image-source image, with the four border-image-slice cuts at 124px dividing the image into nine parts.

The border-image-source image, with the four border-image-slice cuts at 124px dividing the image into nine parts. — The `border-image-source` image, with the four `border-image-slice` cuts at 124px dividing the image into nine parts.

The rest of the border properties then interact to lay out the tiles as follows:

Diagram of all border-image properties and how they interact, and showing the rendering with and without the border-image in effect. — Diagram of all `border-image` properties and how they interact, and showing the rendering with and without the `border-image` in effect.

Here, even though the border-width is 12px, the border-image-width property computes to 124px. The border-image area is then outset 31px from the border-box and into the margin area. If the border-image fails to load (or border images are not supported by the browser), the fallback rendering uses a green double border.

Live Demo

Play with the values of the border-image property in the following demo to see how that changes the result of the following border image.

View this demo on the Codrops Playground

Browser Support

CSS3 Border images

Method of using images for borders

W3C Candidate Recommendation

Supported from the following versions:

Desktop

Mobile / Tablet

* denotes prefix required.

Supported:
Yes
No
Partially
Polyfill

Stats from caniuse.com