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 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 isstretch
, 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
orspace
, 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
, orspace
, 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 isspace
, 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
iscollapse
- 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:
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:
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 rest of the border properties then interact to lay out the tiles as follows:
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.
Browser Support
CSS3 Border images
Method of using images for borders
W3C Candidate Recommendation
Supported from the following versions:
Desktop
- 56
- 50
- 11
- 43
- 15
Mobile / Tablet
- 15
- 129
- No
- 129
- 130
Further Reading
- CSS Backgrounds and Borders Module Level 3
- Border Image Explained by Dudley Storey
- Border Image Generator—Interactive Demo and Tool
- Grokking CSS3 border-image—Interactive Demo