Favorites

Creating Gradient Borders with CSS

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee
Gradient Borders with CSS

Gradient basics

A gradient border is a border that blends smoothly between two or more colours, instead of being a single solid colour. It's an easy way to make a card, button or image stand out.

CSS doesn't have a border-color value that accepts a gradient, so we need to borrow gradients from elsewhere. Gradients in CSS are a type of image, created with functions like these:

/* Colours blend along a straight line */
linear-gradient(135deg, #2563eb, #db2777)

/* Colours spread out from a point */
radial-gradient(circle at top left, #db2777, #2563eb)

/* Colours sweep around a point, like a clock hand */
conic-gradient(#2563eb, #db2777, #f59e0b, #2563eb)

Because a gradient is an image, it can be used anywhere CSS accepts an image, including border-image, background and mask. Those three properties give us three ways to make gradient borders, each with its own strengths.

Tip: to design the gradient itself, try our CSS Gradient Generator, then paste the result into any of the methods below.

Method 1: border-image

The simplest method uses the border-image property, which paints an image (in our case, a gradient) into the border area:

.box {
  border: 4px solid;
  border-image: linear-gradient(135deg, #2563eb, #db2777) 1;
}
Results
border-image
border-image with border-radius: 16px
  • border: 4px solid sets the width of the border. The colour doesn't matter, because the image replaces it.
  • The 1 after the gradient is the slice value. It tells the browser how to cut the image up for the border's edges and corners. For a gradient, 1 simply means "use the whole gradient".

The catch is that border-image ignores border-radius. The box on the right has border-radius: 16px, but its corners stay square. For rounded corners, use method 2 or 3.

Method 2: background layers

This is the most popular method, and it supports rounded corners. The idea is to give the element two background layers:

  1. a solid colour on top, filling only the padding box (the inside of the element, within the border)
  2. the gradient underneath, filling the whole border box (including the area under the border)

Make the border itself transparent, and the gradient shows through it:

.box {
  border: 4px solid transparent;
  border-radius: 16px;
  background:
    linear-gradient(#ffffff, #ffffff) padding-box,
    linear-gradient(135deg, #2563eb, #db2777) border-box;
}
Results
Background layers with rounded corners

The first layer, linear-gradient(#ffffff, #ffffff), is a "gradient" from white to white: a solid colour written as an image. That's needed because only the last layer of a background can be a plain colour, and here we want the solid colour on top.

Simpler than before: the original version of this post used a double border style and separate background-image, background-clip and background-origin properties. Writing padding-box and border-box inside each layer of the background shorthand does the same job in fewer lines.

The one limitation is that the inside must be a solid colour that matches whatever sits behind it. On a patterned or image background, you'd see a white box. If your site has a dark mode, use a custom property for that colour, such as linear-gradient(var(--bg), var(--bg)) padding-box.

Method 3: a masked pseudo-element

When the inside of the element needs to stay transparent, for example on a patterned background or over an image, you can draw the border on a ::before pseudo-element and use a mask to cut out its middle:

.box {
  position: relative;
  border-radius: 16px;
}

.box::before {
  content: "";
  position: absolute;
  inset: 0;                    /* cover the whole element */
  padding: 4px;                /* the border width */
  border-radius: inherit;      /* match the element's corners */
  background: linear-gradient(135deg, #2563eb, #db2777);
  mask:
    linear-gradient(#000 0 0) content-box,
    linear-gradient(#000 0 0);
  mask-composite: exclude;     /* keep only where the two masks differ */
  pointer-events: none;        /* let clicks pass through */
}

The striped background shows through all three boxes below. Each one uses the masked pseudo-element:

Results
Transparent inside
Rounded corners
On any background

Here's how the mask works:

  • The pseudo-element covers the whole box and is filled with the gradient.
  • The mask has two layers. One covers only the content box (inside the 4px padding), and the other covers everything.
  • mask-composite: exclude keeps only the areas where the layers don't overlap, which is the 4px ring around the edge. Everything inside becomes transparent.

Animated gradient borders

A conic-gradient() starting from a rotating angle makes the colours sweep around the border. To animate the angle, register it as a typed custom property with @property, so the browser knows it holds an angle and can animate it smoothly:

@property --angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

@keyframes spin {
  to { --angle: 360deg; }
}

.box {
  border: 4px solid transparent;
  border-radius: 16px;
  background:
    linear-gradient(#ffffff, #ffffff) padding-box,
    conic-gradient(from var(--angle), #2563eb, #db2777, #f59e0b, #2563eb) border-box;
  animation: spin 4s linear infinite;
}

/* Keep it still for people who prefer less motion */
@media (prefers-reduced-motion: reduce) {
  .box {
    animation: none;
  }
}

Instead of a constant animation, you can also transition the angle when the element is hovered or focused. Hover over, or tab to, the card on the right:

Results
Animated with @keyframes
Hover or focus me
.card {
  transition: --angle 0.8s ease;
}

.card:hover,
.card:focus-visible {
  --angle: 180deg;
}

Tip: use moving borders sparingly. A constantly animating border pulls attention away from everything else on the page, so it's best saved for one special element, like a featured offer.

More variations

Gradient on one side only

border-image is ideal for single-side borders, such as a gradient underline on a heading or an accent stripe down the side of a quote. Because these are straight lines, the lack of rounded corners doesn't matter:

h2 {
  padding-bottom: 6px;
  border-bottom: 4px solid;
  border-image: linear-gradient(90deg, #2563eb, #db2777) 1;
}

blockquote {
  border-left: 6px solid;
  border-image: linear-gradient(#15803d, #2563eb) 1;
}
Results
A heading with a gradient underline
A quote or callout with a gradient accent down the left side.

Pill buttons and radial gradients

The background layers method works with any border-radius, including fully rounded pill shapes, and with any type of gradient:

.pill {
  border: 3px solid transparent;
  border-radius: 999px;
  background:
    linear-gradient(#ffffff, #ffffff) padding-box,
    linear-gradient(90deg, #f59e0b, #db2777, #7c3aed) border-box;
}

.radial {
  border: 6px solid transparent;
  border-radius: 16px;
  background:
    linear-gradient(#ffffff, #ffffff) padding-box,
    radial-gradient(circle at top left, #db2777, #2563eb 70%) border-box;
}
Results
A radial gradient border

Which method should you use?

MethodRounded cornersTransparent insideBest for
border-imageNoYesSquare boxes, and single-side lines like underlines
Background layersYesNo (needs a solid colour)Most cards and buttons on a plain background
Masked pseudo-elementYesYesElements over images or patterned backgrounds
  • Accessibility: if the border is the only thing showing where a button or field is, make sure even the lightest colour in the gradient has a contrast ratio of at least 3:1 against the background.
  • Dark mode: with the background layers method, remember to change the inner colour for dark themes.

Wrapping up

CSS has no gradient border colour, but gradients can be painted into the border in three ways. border-image is the quickest for square corners and single sides, background layers handle rounded corners with a solid inside, and a masked pseudo-element gives you rounded corners with a transparent inside. Add @property and a conic-gradient(), and you can even animate them.

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee