The new CSS3 property border-image is a little tricky, but it can allow you to create flexible boxes with custom borders (or drop shadows, if that’s your thing) with a single div and a single image. In this article, I explain how the border-image shorthand property works in today’s browsers.

The basic idea

The border-image shorthand property has 3 parts:

border-image: url(border-image.png) 25% repeat;

Essentially, these allow you to specify:

1. An image to use as the border
2. Where to slice that image, dividing the image into 9 sections
3. How the browser should apply those sections to the edges of your element

The pertinent details

Let’s look at each part of the process in a little more detail. The first part is easy, and is familiar from the background-image property. For demonstration purposes I’ll use this image, which is 100px x 100px:

Slicing your image

The second part can have from one to four values, much like the border-width property, and they are specified in the same order: top, right, bottom, left. You can use percentages or pixels. Strangely, the percentages require the “%”, while pixels should be listed without the “px”:

border-image: url(my-image.gif) 25% 30% 10% 20% repeat;
border-image: url(my-image.gif) 25 30 10 20 repeat;

In this case, since my image is 100px x 100px, the two rules above are equivalent – they slice the image in the same places. I’ve added some dimensions on my image to demonstrate:

Repeat, Round, Stretch

border-image will always place the corner sections of your image into the corresponding corners of your element box, but the third part of the shorthand rule tells the browser how to treat the middle sections of your image – the ones that will go along the edges of your element.

Repeat (repeat, or tile, the image) and stretch (stretch, or scale, the image) are pretty self-explanatory.

Round means tile the image but only so that a whole number of tiles fit, and otherwise scale the image. Right now, Safari and Chrome interpret round as repeat. There can be up to two values: one for the top and bottom edges of the element, and one for the left and right.

Here’s an example with the top/bottom value set to repeat, and the left/right value set to stretch:

#example-one {
  border-width: 25px 30px 10px 20px;
  border-image: url("border-image.png") 25 30 10 20 repeat stretch;
}

LIVE DEMO, RSS READERS CLICK OVER TO SEE. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean eu arcu non dui consequat vestibulum non vitae eros. Donec imperdiet lorem at mi rhoncus lacinia. Phasellus porttitor ligula eu justo condimentum eget placerat arcu pharetra. Proin fringilla vulputate eros in accumsan. Sed mi nibh, pulvinar eu sollicitudin ut, feugiat non ipsum. In ornare, quam sit amet tempor suscipit, erat odio suscipit nisi, eu gravida nisl orci ut arcu. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Border-width

border-image won’t do anything if you don’t specify a width for your border. For browsers that understand border-image, your image slices will be scaled to the specified width. If you use the border shorthand property, it provides a nice fallback for browsers that don’t:

#example-two {
  border: 50px double orange;
  border-image: url("border-image.png") 25 30 10 20 repeat;
}

Or you can specify each width individually (in this example I’ve specified widths such that the image slices aren’t scaled at all):

#example-three {
  border-color: orange;
  border-style: double;
  border-width: 25px 30px 10px 20px;
  border-image: url("border-image.png") 25 30 10 20 repeat;
}

Using a plain border at the same widths as your border-image won’t always be ideal, however, so you may want to use conditional stylesheets to give IE some different border styles altogether.

Browser quirks

Predictably, IE doesn’t understand anything of border-image. Browsers that do support border-image only support the shorthand property, not all the individual properties that are described in the spec. Some potentially useful properties aren’t supported at all, especially border-image-outset, which would solve this problem.

Also, the default behavior is supposed to be to discard the center section of the image, and use the ‘fill’ keyword on the border-image-slice property to preserve it:

The fill keyword, if present, causes the middle part of the border-image to be preserved. (By default it is discarded, i.e., treated as empty.) (Read the spec)

But the current browser behavior is to preserve the middle, and there is no way to turn it off. Thus, if you don’t want your element’s content area to have a background, the center section of your image must be empty. However, you can use this filling behavior to your advantage, to create a box with a fancy border and background, with only one image.

Interactive demo

I built a border-image demo page to help me get my head around this complicated new set of CSS3 properties. You can pick an image, specify repeat, round, or stretch, and adjust the border-width and slicing. Enjoy!

Examples in the wild

• Chris Spooner uses it to nice effect to give his images a custom border.
• On the travel blog Go Pink Boots (Update: now offline) I built recently, I used it to add a torn-paper background to images.
• I use it on my site The Web Designers’ Review of Books (Update: now offline) to highlight blockquotes.

If you have other examples on live sites, I’d love to see them. Leave a link in the comments!