Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 139 ยท The Box Model

Border Images

Learn CSS border-image, from source, slice, width, outset and repeat to gradient borders, custom dashed lines and how to combine gradient borders with rounded corners.

A normal border is a line: solid, dashed, dotted or one of the 3D styles you met in Borders. Sometimes you want more than a line, like a decorative picture frame, a stamp-style edge, a gradient outline or dashes with exactly the length and gap you choose. That is what border-image is for.

With border-image, the browser takes an image (a file, an SVG or a gradient), cuts it into nine pieces, and paints those pieces into the border area of the box. The corners stay corners, the edges stretch or repeat along the sides, and the box still behaves like any other box. In this lesson you will learn how that slicing works, what each of the five longhand properties does, and how to build the most popular use today: gradient borders.

The nine-slice idea

Imagine drawing two horizontal and two vertical lines across an image, like a tic-tac-toe grid. You get nine regions:

TEXT
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ corner โ”‚   top edge   โ”‚ corner โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  left  โ”‚    middle    โ”‚ right  โ”‚
โ”‚  edge  โ”‚  (optional)  โ”‚  edge  โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ corner โ”‚  bottom edge โ”‚ corner โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The browser places the four corners in the four corners of the border, unchanged in shape. It stretches or tiles the four edges along the sides. The middle is thrown away unless you ask to keep it.

The sample image for this lesson is a 90 ร— 90 SVG built as a grid of 30 ร— 30 tiles: dark corners with a gold diamond, light edges with a purple dot, and a pale middle. Cutting it 30 units in from every side lines the slices up exactly with the tiles.

CSS
.framed {
  border: 30px solid #c4b5fd;   /* the width matters; the color is a fallback */
  border-image: url("/samples/css-border-images-frame.svg") 30;
}
A first border image

Always set a border style. A border image is drawn in the border area, and by default it is as wide as border-width. If border-style is none (the initial value), the used border width is 0 and nothing appears. Write a full border declaration first, and its color doubles as a fallback if the image fails to load.

The five longhand properties

border-image is a shorthand for five properties. Here they are one at a time.

border-image-source

The image to use: url(...), any gradient function, or none (the default, which shows the ordinary border). SVG is a great choice because it stays sharp at any size.

border-image-slice

Where to cut the image, measured inward from the top, right, bottom and left edges, in the same order as margin and padding:

  • A plain number means image pixels for raster images, or SVG coordinates for vector images: 30. Do not write px here.
  • A percentage is relative to the image size: 33.33% cuts at a third.
  • One to four values, like 30 or 20 40 (top/bottom, then left/right).
  • Add the keyword fill to keep the middle slice and paint it behind the content, like a background.

border-image-width

How wide the painted image is. It defaults to 1, which means one times border-width. You can also use a length (20px), a percentage of the box, or auto (the slice's natural size). It takes one to four values like the others.

If border-image-width differs from border-width, the image can spill into the padding, or leave part of the border empty. Layout always uses border-width; the image just paints over that area.

border-image-outset

Pushes the image outward, beyond the border box, by a length or a multiple of border-width. Like an outline, the outset part takes up no space in the layout, so it can overlap neighbors.

border-image-repeat

How the edge slices fill the sides. One value applies to all sides; two values set horizontal edges, then vertical edges.

Value What the edges do
stretch Stretch one slice to fill the side (the default)
repeat Tile the slice; partial tiles get cut off at the ends, and the tiling is centered
round Tile and resize the tiles so a whole number fits
space Tile whole tiles and spread the leftover space evenly between them

Compare the four repeat values on the same frame. Watch the purple dots along the edges:

stretch, repeat, round and space

stretch turns each dot into a long smear. repeat keeps the tile size and cuts off the ends. round squeezes or grows the tiles a little so whole dots fit, which is usually the nicest choice for patterns. space keeps the tiles exactly the size of the border and puts gaps between them. Drag the editor wider or change the heights to see round and space adapt.

The shorthand

The border-image shorthand takes the values in this order, with slashes between slice, width and outset:

CSS
border-image: <source> <slice> / <width> / <outset> <repeat>;

/* examples */
border-image: url("frame.svg") 30 round;
border-image: url("frame.svg") 30 fill / 20px / 6px round;
border-image: url("frame.svg") 30 / 1 / 0 stretch;   /* the defaults written out */

You can leave out width and outset, but if you want an outset without changing the width, you still need both slashes: 30 / / 8px. Any longhand you leave out is reset to its initial value, as with all shorthands.

Use this playground to see how slice, fill, width and outset interact:

Slice, fill, width and outset

With fill, the pale middle tile paints behind the text. Slicing at 15 cuts through the middle of each tile, so the corners show only part of the diamond and the edges mix two colors. A smaller border-image-width draws a thin frame and leaves the rest of the 20px border empty, and the outset pushes the whole frame outside the box without moving anything around it.

Watch out: the border shorthand also resets every border-image longhand to its initial value. That's why the variant rules above are written as .row .a and not just .a. A plain .a would lose to .row div, whose border: 20px solid silently sets border-image-slice back to 100%, and every frame would collapse into four tiny copies of the image in the corners. Set border first and border-image after it, in a rule that wins the cascade.

Gradient borders

The most common use of border-image today has no image file at all. Because gradients are images, you can paint a border with one:

CSS
.card {
  border: 4px solid;
  border-image: linear-gradient(135deg, #f97316, #db2777, #6366f1) 1;
}

The 1 is the slice. A gradient has no fixed size, so any small number works: it cuts a thin strip from each side of the gradient, and those strips stretch along the edges. It is a quick, solid technique, but it has one big limitation: border-image ignores border-radius. The border stays square even when the background is rounded.

For rounded gradient borders, use two background layers instead. You saw background-clip and background-origin in Multiple Backgrounds and background-clip:

CSS
.rounded-card {
  border: 4px solid transparent;
  border-radius: 16px;
  background:
    linear-gradient(white, white) padding-box,
    linear-gradient(135deg, #f97316, #db2777, #6366f1) border-box;
}

The first layer is a solid white fill clipped to the padding box. The second is the gradient, painted under it and reaching all the way to the border box, so it only shows through the transparent border. Both layers follow the radius.

Square and rounded gradient borders

The third card shows a handy detail: a border image only paints where there is a border. With only border-top set, the gradient appears on the top edge alone, which makes a neat accent line.

Dark backgrounds. The two-background trick needs a solid inner color that matches the card. If the card must be see-through, use the mask technique from Clip Paths and Masks, or accept square corners with border-image.

Custom dashes and other practical patterns

border-style: dashed gives you whatever dash length the browser chooses. A repeating gradient as a border image lets you choose:

CSS
.coupon {
  border: 3px solid;
  border-image: repeating-linear-gradient(90deg, #0f766e 0 12px, transparent 12px 20px) 3;
}

A gradient border image is painted at the size of the whole box and then sliced, so with a gradient running sideways only the top and bottom edges get dashes. The side edges are cut from thin vertical strips at the far left and right of the gradient, so they come out solid or empty, depending on where the pattern ends. For dashes on every side, draw four background gradients instead. The example below shows both options, plus a stitched ribbon and a rainbow frame.

Dashes, stripes and rainbows

The ribbon slices a diagonal stripe pattern, so every edge shows stripes. The rainbow frame slices a conic gradient: each edge takes the colors that happen to lie along that side of the box, so the hues flow around the frame. Try changing the angles and stripe widths.

When should you reach for border-image?

  • Decorative frames for certificates, cards or game interfaces, where an SVG gives you exact corners.
  • Gradient outlines on square or one-sided borders: buttons, tabs, headings, accent bars.
  • Custom patterned edges such as stitches, ribbons or stamp-like frames drawn in SVG.

For ordinary rounded borders, a plain border plus border-radius is simpler and works better with forced-colors (high contrast) modes. Keep border images decorative: any meaning they carry, such as "this item is selected", should also be expressed in another way, like text, an icon or a change in weight.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You set border-image on a box but nothing appears. Which missing declaration is the most likely cause?

    Without a border style, the border width is 0, and by default the border image is drawn one border-width wide, so nothing shows.
  2. 2. What does border-image-slice: 30 mean for an SVG image?

    Plain numbers are image pixels for raster images and coordinates for vector images. Percentages need a % sign, and the width is a separate property.
  3. 3. Which border-image-repeat value tiles the edge slices and resizes them so a whole number of tiles fits?

    round scales the tiles so they fit exactly. space keeps their size and adds gaps; repeat keeps their size and cuts off partial tiles.
  4. 4. Why might you prefer two background layers over border-image for a gradient border?

    Gradients work fine as border images, but the corners stay square. Layering a padding-box fill over a border-box gradient follows the radius.
  5. 5. What does the fill keyword in border-image-slice do?

    By default the middle region of the image is discarded. With fill, it is drawn over the padding and content area, like a background.

Summary

  • border-image cuts an image into nine slices and paints them into the border area: corners stay put, edges stretch or tile.
  • It needs a real border (border: 20px solid) because its default width is one times border-width.
  • border-image-slice sets where to cut (numbers without units, or percentages); fill keeps the middle.
  • border-image-width and border-image-outset change where the image paints without changing the layout.
  • border-image-repeat chooses stretch, repeat, round or space for the edges.
  • Gradients make great border images (linear-gradient(...) 1), but border-image ignores border-radius; for rounded gradient borders, layer a padding-box fill over a border-box gradient.

Next: Outlines, the line that sits outside the border and makes keyboard focus visible.