Using the CSS border-image property

Last updated:

The CSS property border-image lets you use an image for a border rather than just a styled line. The syntax for it is relatively complex, though, and seems to cause some confusion at first. I think it could benefit from a good introductory section giving a quick overview of the properties, but in lieu of that, here's my own rundown:

First, pay attention to the effects that border-image has on the geometry of the element: none. border-image is purely a painting effect, and won't make the box bigger or shift the contents around to keep them out of the way. You can use the ordinary border-width property for that; using border-image suppresses the *display* of a normal border, but the invisible border will still change the size of the box like normal, so you can use it to make sure there's a sufficiently large clear area around the box and you don't end up obscuring the contents.

Now, the reason border-image gets a bit complicated is that you have to deal with two separate boxes getting sliced into regions: the element's box and the image's box. It's not immediately apparent which properties affect what.

The border-image-source property specifies the image to be used, and then border-image-slice specifies how to slice up the image. You give it four lengths (or less, and they'll get filled in like margins or paddings or borders do) and it measures distances from each edge accordingly.

In this image, the four numbers given were 25% 30% 12% 20%. You can see how the lines were measured accordingly from each edge, starting from the top and going clockwise, like normal for CSS.

Now that you've measured the four lines, you just use these to slice up the image into 9 pieces. Normally you throw away the center piece and just use the outer 8 (after all, this is a border image, which should be painting around the content), but you can specify fill in the property as well to keep the middle chunk around. It'll then act like a bottommost background layer.

So you have the image pieces, and now we have to specify where to put these on the box with border-image-width. This works the same way as it did with border-image-slice - you give it four lengths, and it cuts regions by measuring each length from the appropriate border edge.

There's one wrinkle, though - you may want the border-image to spill outside of the element's box somewhat. For example, your border-image may include its own shadow, or it may just be complex and need a little bit of extra space. The border-image-outset property lets you specify how much to grow the border box by in each direction. This growth happens before you do the measurements specified by border-image-width.

At this point you have 8 image pieces, and 8 regions to fill with an image (or maybe 9 of each, if you're using the center piece). The images are automatically partially scaled: top and bottom images are scaled to be as high as the top and bottom regions, left and right images are made as wide as the left and right regions, and the corner images are scaled to the width and height of the corner regions. border-image-repeat then specifies how to finish out the scaling/repetition: whether to scale or tiled the top and bottom images horizontally and the left and right images vertically, and how precisely to do so. (Also, scaling/tiling the center image in both directions, if you're using it.)

The shorthand then combines all of this together in a dense (and thus, unfortunately, difficult to read) manner - the three properties that accept lengths (-slice, -width, and -outset) must be specified in that order, and separated by slashes to prevent any ambiguity, but the -source, -repeat, and the lengths as a whole can be given in any order.

Note that current implementations of border-image are relatively buggy, and may or may not conform to particular details listed here.

(a limited set of Markdown is supported)