CSS Border Image

What is CSS Border Image?

The border-image CSS property draws an image around a given element, replacing the element's regular border. Unlike standard CSS borders limited to solid, dashed, or dotted lines, border-image enables sophisticated decorative borders using any image source.

This comprehensive guide covers the syntax, five constituent properties, and practical techniques for implementing border images in modern web design.

When combined with other CSS techniques like CSS gradients, you can create lightweight, resolution-independent decorative elements that enhance user engagement without impacting page load performance.

The Five Constituent Properties

The border-image property is a shorthand that combines five individual properties. Understanding each component gives you precise control over border rendering.

1. border-image-source

Specifies the source image. Can be a URL to an image file, a CSS gradient, or none. The fill keyword displays the middle region as background.

/* Using an image file */
border-image-source: url("border-pattern.png");

/* Using a CSS gradient */
border-image-source: linear-gradient(to right, #f6b73c, #4d9f0c);

/* No image - fall back to border-style */
border-image-source: none;

2. border-image-slice

Defines how the source image is divided into regions. The image is conceptually sliced into nine regions (four corners, four edges, and a middle).

/* Single value - all four edges */
border-image-slice: 30;

/* Two values - top/bottom | left/right */
border-image-slice: 30 60;

/* Fill keyword displays the middle region */
border-image-slice: 30 fill;

3. border-image-width

Controls the width of the border image. By default equals border-width but can be set independently.

/* Default - uses border-width */
border-image-width: 1;

/* Explicit widths */
border-image-width: 20px;
border-image-width: 10px 20px;

4. border-image-outset

Specifies how far the border image area extends beyond the border box.

/* Extend border image beyond the element */
border-image-outset: 10px;
border-image-outset: 0 10px 0 10px;

5. border-image-repeat

Defines how the edge regions are scaled and tiled. Four modes: stretch, repeat, round, space.

/* Single value - all sides */
border-image-repeat: round;

/* Two values - vertical | horizontal */
border-image-repeat: round stretch;

Understanding Repeat Modes

The border-image-repeat property determines how border edge regions are scaled and tiled.

stretch

The source image's edge regions are stretched to fill the gap between each border. Creates a continuous stretched look along each edge.

repeat

The source image's edge regions are tiled (repeated) to fill the gap. Tiles may be clipped to achieve the proper fit.

round

The source image's edge regions are tiled (repeated) to fill the gap. Tiles are stretched to achieve the proper fit without clipping.

space

The source image's edge regions are tiled (repeated) to fill the gap. Extra space is distributed between tiles to achieve the proper fit.

Syntax and Value Patterns

The border-image shorthand accepts one to five values in this order:

1. border-image-source
2. border-image-slice (with optional fill)
3. border-image-width (separated by /)
4. border-image-outset (separated by /)
5. border-image-repeat

Code Examples

/* source | slice */
border-image: linear-gradient(red, blue) 27;

/* source | slice | repeat */
border-image: url("/images/border.png") 27 space;

/* source | slice | width */
border-image: linear-gradient(red, blue) 27 / 35px;

/* Full syntax: source | slice | width | outset | repeat */
border-image: url("/images/border.png") 27 23 / 50px 30px / 1rem round space;

For more advanced CSS techniques, explore our guide on CSS transforms and how they can be combined with border-image effects for dynamic visual presentations.

Practical Examples

Example 1: Simple Image Border

.card {
 border: 30px solid;
 border-image: url("border-diamonds.png") 30 round;
}

Example 2: Gradient Border

.gradient-border {
 border: 20px solid;
 border-image: linear-gradient(to bottom right, #f6b73c, #4d9f0c) 20;
}

Example 3: Repeating Pattern Border

.pattern-border {
 border: 60px solid;
 border-image: repeating-linear-gradient(
 45deg,
 #4d9f0c,
 #9198e5,
 #4d9f0c 20px
 ) 60;

For more advanced gradient techniques that work well with border-image, explore our guide to /resources/guides/web-performance/radial-gradient/.

Sources

1. MDN Web Docs: border-image
2. MDN Web Docs: border-image-repeat