CSS `border-image-repeat` Property: A Comprehensive Guide

Table of Contents#

1. Understanding border-image-repeat
2. Syntax
3. Values
   • Stretch
   • Repeat
   • Round
   • Space
   • Two-Value Syntax
4. Practical Examples
   • Example 1: Stretch
   • Example 2: Repeat
   • Example 3: Round
   • Example 4: Space
   • Example 5: Two-Value Combination
5. Common Pitfalls
6. Best Practices
7. References

Understanding border-image-repeat#

Before diving into border-image-repeat, it’s important to grasp the basics of how border-image works. The border-image property uses an image to replace the default border style of an element. To do this, the image is sliced into 9 regions using border-image-slice: 4 corners, 4 edges (top, right, bottom, left), and a middle region (which is typically transparent and not visible by default).

The border-image-repeat property specifically controls how the edge regions (top, right, bottom, left) of the sliced image are tiled or stretched to fill the border area. The corner regions are always displayed as-is (they are not repeated or stretched).

Syntax#

The border-image-repeat property can take one or two values. The syntax is:

border-image-repeat: <repeat-style>;
/* Or for horizontal and vertical control: */
border-image-repeat: <horizontal-repeat> <vertical-repeat>;

• If one value is provided, it applies to both horizontal (left/right edges) and vertical (top/bottom edges) repetition.
• If two values are provided, the first controls horizontal repetition, and the second controls vertical repetition.

Values#

border-image-repeat accepts four main values, each dictating a different tiling behavior for the border image edges.

stretch (Default)#

The stretch value stretches the edge regions of the image to fill the entire border area. This can distort the image if the border’s dimensions don’t match the image’s aspect ratio.

Behavior: The edge image is scaled (stretched or compressed) to fit the border’s length/width.

repeat#

The repeat value tiles (repeats) the edge regions of the image to fill the border area. If the image doesn’t fit perfectly, the last tile may be cut off.

Behavior: Tiles the image from start to end; excess is clipped.

round#

The round value tiles the image, but scales it slightly to ensure an integer number of tiles fit within the border area. This avoids clipping and ensures a clean, full tile at the end.

Behavior: Tiles the image, scaling it up/down to fit a whole number of tiles.

space#

The space value tiles the image without scaling, but adds extra space between tiles if needed to ensure an integer number of tiles fit. No clipping occurs, but gaps may appear between tiles.

Behavior: Tiles the image, adding space between tiles to fit a whole number of tiles.

Two-Value Syntax#

You can specify different behaviors for horizontal and vertical edges by passing two values:

• First value: Horizontal repetition (left/right edges).
• Second value: Vertical repetition (top/bottom edges).

Example: border-image-repeat: repeat round; (horizontal: repeat, vertical: round).

Practical Examples#

To illustrate border-image-repeat, we’ll use a sample border image: a 60x60px PNG with a 20px "slice" (i.e., border-image-slice: 20). The image has a decorative pattern (e.g., a dotted line or geometric shape) in its edge regions.

Example 1: stretch#

CSS:

.stretch-border {
  width: 300px;
  height: 150px;
  border: 20px solid; /* Fallback border */
  border-image-source: url('border-pattern.png');
  border-image-slice: 20; /* Slice image into 20px regions */
  border-image-width: 20px; /* Border width */
  border-image-repeat: stretch; /* Default behavior */
}

Result: The edge regions of border-pattern.png are stretched to fill the 300px (horizontal) and 150px (vertical) borders. If the original edge image is 20px wide, it will be stretched to 300px (horizontal) and 150px (vertical), potentially distorting the pattern.

Example 2: repeat#

CSS:

.repeat-border {
  width: 300px;
  height: 150px;
  border: 20px solid;
  border-image-source: url('border-pattern.png');
  border-image-slice: 20;
  border-image-width: 20px;
  border-image-repeat: repeat;
}

Result: The edge image tiles repeatedly. For a 300px horizontal border and 20px-wide edge image, there will be 15 tiles (300/20 = 15). If the border width is 310px, there will be 15 full tiles (300px) and 10px of a 16th tile, which is clipped.

Example 3: round#

CSS:

.round-border {
  width: 310px; /* Not a multiple of 20px */
  height: 150px;
  border: 20px solid;
  border-image-source: url('border-pattern.png');
  border-image-slice: 20;
  border-image-width: 20px;
  border-image-repeat: round;
}

Result: The edge image scales slightly to fit a whole number of tiles. For 310px horizontal border:

• 310 / 20 = 15.5 tiles → round scales the image to 310 / 15 ≈ 20.67px per tile, ensuring 15 full tiles fit without clipping.

Example 4: space#

CSS:

.space-border {
  width: 310px;
  height: 150px;
  border: 20px solid;
  border-image-source: url('border-pattern.png');
  border-image-slice: 20;
  border-image-width: 20px;
  border-image-repeat: space;
}

Result: The edge image tiles without scaling, but adds space between tiles. For 310px horizontal border:

• 310 / 20 = 15.5 tiles → space uses 15 tiles (300px) and adds 10px of space (distributed evenly between tiles: 10px / 14 gaps ≈ 0.71px per gap).

Example 5: Two-Value Combination#

CSS:

.two-value-border {
  width: 300px;
  height: 160px;
  border: 20px solid;
  border-image-source: url('border-pattern.png');
  border-image-slice: 20;
  border-image-width: 20px;
  border-image-repeat: repeat round; /* Horizontal: repeat, Vertical: round */
}

Result:

• Horizontal edges (left/right): Tiles with repeat (may clip).
• Vertical edges (top/bottom): Tiles with round (scaled to fit whole tiles).

Common Pitfalls#

1. Forgetting border-image-slice: border-image-repeat has no effect without border-image-source and border-image-slice. Always define these properties first.

   • Example: border-image-slice: 20; (slices the image into 20px regions).

2. Mismatched border-image-width and Image Size: If border-image-width is larger than the sliced edge region, stretch will distort the image, while repeat may produce tiny, repeated tiles.

3. Overusing stretch: stretch is the default, but it often distorts images. Prefer round or repeat for better visual quality.

4. Ignoring Browser Compatibility: While border-image is supported in all modern browsers, older browsers (e.g., IE < 11) do not support it. Always include a solid border fallback.

5. Using space with Small Images: space can create excessive gaps if the border is much larger than the image. Use round instead for tighter tiling.

Best Practices#

1. Use round for Clean Tiling: round ensures no clipping and minimal distortion, making it ideal for patterns (e.g., stripes, dots).

2. Test with Multiple Border Sizes: Borders may vary in size (e.g., responsive designs). Test border-image-repeat with different element dimensions to ensure consistency.

3. Optimize Border Images: Use small, lightweight images (e.g., SVG) for border patterns to reduce load times.

4. Combine with border-image-outset: If the border image is too small, use border-image-outset to extend it beyond the border box (e.g., border-image-outset: 5px;).

5. Fallback for Older Browsers: Always define a solid border as a fallback (e.g., border: 20px solid #333;).

6. Use Tools for Slicing: Tools like Border Image Generator can help visualize slices and repetition.

References#

• MDN Web Docs: border-image-repeat
• W3C Specification: border-image-repeat
• Can I Use: border-image (Browser compatibility)
• CSS-Tricks: Border Images

By mastering border-image-repeat, you can create unique, professional borders that elevate your web designs. Experiment with different values and image patterns to unlock endless creative possibilities!