CSS Gradient Borders

CSS Gradient Borders Without JavaScript

Two CSS techniques produce gradient borders, and the choice between them comes down to one question: does the element have rounded corners? The border-image property accepts a gradient directly and renders it as the border fill, but it does not respect border-radius¹. The background-clip masking technique layers a gradient background behind a clipped inner element, preserving rounded corners².

Square elements and simple rectangular borders can use border-image without restriction. Rounded cards, pill buttons, and circular elements require the masking technique because border-image ignores border-radius regardless of the specified value. No JavaScript is needed for either approach; both rely entirely on CSS properties available in all modern browsers. The CSS Gradient Builder on this page outputs the gradient value needed for either technique.

The border-image approach

border-image accepts a gradient function as its source: border-image: linear-gradient(to right, blue, orange) 1¹. The trailing 1 is the slice value, which tells the browser to use the full gradient as the border image without scaling. Combine it with border-style: solid (required) and border-width to control the border thickness. The slice value offers limited control over corner rendering, and non-1 values slice the border image into nine pieces for corner-specific styling, which is rarely needed for simple gradient effects.

Limitations and browser behavior

border-image overrides border-color and ignores border-radius entirely. The border renders as straight segments even when border-radius is set on the element, because the border-image property replaces the standard border rendering pipeline with its own image-based fill mechanism. This makes border-image appropriate for rectangular elements and table cells but not for rounded UI components. Consequently, any design requiring rounded gradient borders requires a different approach, such as the background-clip masking technique described in the next section.

When to avoid border-image

The slice value offers limited control over corner rendering, and the property cannot combine with background-image on the same element without one covering the other. Building on this, the 1 slice value works for most gradient borders; non-1 values slice the border image into nine pieces for corner-specific styling, which is rarely needed for simple gradient effects. Furthermore, border-image does not animate smoothly with CSS transitions, so designs that require gradient color changes on hover or focus should use the masking technique instead.

The background-clip masking approach

The masking technique applies a gradient background to the element and uses background-clip with a transparent inner layer to reveal the gradient only at the border area². The element sets padding equal to the desired border width, background: linear-gradient(...) as the outer gradient, and background-clip: padding-box on an inner layer or a ::before pseudo to create the inset content background. The padding value directly controls the border thickness, so adjusting the padding from 2px to 4px doubles the visible border width without changing the gradient function itself.

Implementation with padding and ::before

One practical pattern: set background: linear-gradient(...) on the element for the border, then apply a background-color on a ::before pseudo-element sized to fill the inner content area (position: absolute; inset: 2px). The pseudo-element background should match the surrounding page surface so the content area reads as a solid panel rather than a transparent cutout. The gradient shows through the 2-pixel gap around the pseudo-element.

Applying border-radius to both the element and the ::before pseudo, with a 2-pixel radius reduction for the inner element, preserves the rounded corners correctly. Because the padding value directly controls the border thickness, you can size a gradient border for a rounded card by moving the padding from 2px to 4px, which doubles the visible border width without changing the gradient function itself. For elements that already use both pseudo-elements for other effects, wrapping the content in an inner div and applying the gradient background to the outer wrapper avoids pseudo-element conflicts.

Browser support, border-radius workaround, and animation

border-image has full support in all modern browsers. The background-clip masking approach also has full support, since it uses only background, position, and border-radius properties. Neither technique requires any flags or polyfills. Use border-image for rectangular elements: table cells, square badges, blocky UI. Use background-clip masking for any element with border-radius: rounded cards, pill buttons, circular icons, search inputs. Yet the masking technique adds a pseudo-element, which may conflict with existing ::before or ::after pseudo-elements on the same element. In that case, wrap the element's content in an inner div and apply the masking background to the outer wrapper.

Animating a gradient border requires animating the stop colors rather than the border-image value directly. Registering the start and end stop colors as typed color properties with @property enables smooth interpolation in a @keyframes rule³. Assign the registered properties as stop values inside the border-image gradient function, then apply the animation to the element. For a hover-only border color change, defining a custom property in :root and updating it in :hover with a property override works in all modern browsers. Without @property registration, the transition between the two values falls back to discrete switching rather than smooth interpolation at the midpoint. Registering the property with @property upgrades the hover transition to a smooth blend.

Gradient borders in Tailwind CSS with arbitrary values

Tailwind CSS arbitrary values handle both gradient border techniques. For the border-image approach, apply the gradient as an arbitrary property: [border-image:linear-gradient(to_right,_#e66465,_#9198e5)_1]. The underscore encoding replaces spaces inside the bracket, and the trailing _1 is the slice value required by border-image.⁴ A border width class (border-2) and border-style: solid are also required for the border-image to render.

For the masking technique in Tailwind, apply the gradient as the element background with p-[2px] padding on the outer wrapper and bg-[linear-gradient(...)] for the gradient layer. The inner element receives a bg-white or bg-base class. Arbitrary values handle oklch() colors directly from the gradient builder: bg-[linear-gradient(135deg,_oklch(0.75_0.18_250),_oklch(0.65_0.15_300))]. Defining the gradient border in a CSS file and applying it with Tailwind's @apply directive avoids repeating long arbitrary value strings across multiple templates, and changing the definition propagates to every component that uses it.⁵

When to use this

Use border-image for rectangular elements where border-radius is not needed. Use the background-clip masking technique for any rounded element requiring a gradient border. The two techniques are not interchangeable on rounded elements.

Examples