HTML Guides for linear-gradient

The linear-gradient() function went through several syntax revisions during CSS standardization. Early drafts and vendor-prefixed implementations (like -webkit-linear-gradient()) used bare direction keywords such as top, bottom left, etc., where the keyword indicated the starting point of the gradient. The final standard, defined in the CSS Images Module Level 3 and Level 4 specifications, changed this so that direction keywords use the to prefix and indicate the ending point of the gradient. For example, the old linear-gradient(top, #fff, #000) meant "start at the top and go to the bottom," while the correct modern equivalent is linear-gradient(to bottom, #fff, #000).

This matters because the old syntax without to is not valid CSS per the current specification. While some browsers may still interpret the legacy syntax for backward compatibility, relying on it is risky — behavior can vary across browsers, and it will trigger validation errors. Using standard-compliant CSS ensures consistent rendering and forward compatibility.

How to fix it

Replace the bare direction keyword with the correct to syntax. Note that the direction meaning is inverted: the old syntax specified where the gradient starts, while the new syntax specifies where it goes to.

Here's a quick mapping from old to new syntax:

Important: Notice that top in the old syntax means "start at top, go to bottom." So the modern equivalent is to bottom, not to top. If the validator message says the argument should be to top, it means you wrote top — but be sure you understand which direction your gradient should actually go before blindly replacing it. If you truly want the gradient to go toward the top, use to top. If you want it to go from the top downward, use to bottom.

If you don't specify a direction at all, linear-gradient() defaults to to bottom (top-to-bottom), which is often what you want.

Examples

Invalid: bare direction keyword

<div style="background: linear-gradient(top, #ffffff, #000000);">

Content

</div>

The bare keyword top is not valid in the standard linear-gradient() syntax and will trigger the validator error.

Fixed: using the to keyword

<div style="background: linear-gradient(to bottom, #ffffff, #000000);">

Content

</div>

Since the old top meant "start at the top," the equivalent standard syntax is to bottom.

Fixed: using an angle

<div style="background: linear-gradient(180deg, #ffffff, #000000);">

Content

</div>

An angle of 180deg produces the same top-to-bottom gradient.

Full document example

<!DOCTYPE html>

<html lang="en">

<head>

<title>Gradient Example</title>

<style>

.box {

width: 200px;

height: 100px;

/* Valid: direction keyword with "to" */

background: linear-gradient(to top, #ffffff, #000000);

}

.box-angle {

width: 200px;

height: 100px;

/* Valid: angle equivalent of "to top" */

background: linear-gradient(0deg, #ffffff, #000000);

}

.box-default {

width: 200px;

height: 100px;

/* Valid: no direction specified, defaults to "to bottom" */

background: linear-gradient(#ffffff, #000000);

}

</style>

</head>

<body>

<div class="box"></div>

<div class="box-angle"></div>

<div class="box-default"></div>

</body>

</html>

All three approaches are valid. Choose whichever is clearest for your use case — the to keyword syntax is generally the most readable, while angles offer more precision for diagonal or non-cardinal directions.

The CSS fill property does not accept linear-gradient() as a valid value.

The fill property is used primarily with SVG elements to define the color that fills the interior of a shape. It accepts simple color values like named colors, hex codes, rgb(), hsl(), currentColor, none, or a reference to an SVG paint server using url().

CSS gradients such as linear-gradient() are classified as <image> values, not <color> values, so they cannot be used directly with fill. This is different from properties like background or background-image, which do accept gradient values.

If you need a gradient fill on an SVG element, you should define a <linearGradient> inside an SVG <defs> block and reference it with url().

How to fix it

Invalid: Using linear-gradient() with fill:

<svg width="100" height="100">

<rect width="100" height="100" style="fill: linear-gradient(to right, red, blue);" />

</svg>

Valid: Using an SVG <linearGradient> definition:

<svg width="100" height="100">

<defs>

<linearGradient id="myGradient" x1="0" y1="0" x2="1" y2="0">

<stop offset="0%" stop-color="red" />

<stop offset="100%" stop-color="blue" />

</linearGradient>

</defs>

<rect width="100" height="100" fill="url(#myGradient)" />

</svg>

The x1, y1, x2, and y2 attributes on <linearGradient> control the direction of the gradient. In this example, x1="0" x2="1" creates a left-to-right gradient, equivalent to to right in CSS.

In the standard linear-gradient() syntax, a side keyword such as top or left must follow the word to, so a gradient whose first argument is a bare keyword is invalid.

The bare form comes from the vendor-prefixed gradients that browsers shipped before the syntax was standardized, such as -webkit-linear-gradient(top, #fff, #000). There, the keyword names the side where the gradient starts. The CSS Images specification changed that: the keyword now comes after to and names the side where the gradient ends. Older stylesheets often repeat the prefixed declaration without the prefix, which leaves the old argument inside the standard function. Current browsers ignore that whole declaration, so the gradient only appears when an earlier prefixed declaration provides it. The validator reports the error on any property that takes an image, such as background, background-image, border-image or list-style-image, and on repeating-linear-gradient() as well.

Writing exactly what the message suggests flips the gradient. The old top means "start at the top", so linear-gradient(top, #fff, #000) was meant to paint white at the top and black at the bottom, while to top paints white at the bottom. To keep the intended look, point to the opposite side: top becomes to bottom, bottom becomes to top, left becomes to right, and right becomes to left. For a corner such as top left, the message names only the first keyword, but both change, so it becomes to bottom right. Because to bottom is the default direction, a gradient that started with top can also drop its first argument.

Invalid example

<style>

.banner {

background-image: linear-gradient(top, #ffffff, #dddddd);

}

</style>

<div class="banner">Free shipping on all orders</div>

Valid example

<style>

.banner {

background-image: linear-gradient(to bottom, #ffffff, #dddddd);

}

</style>

<div class="banner">Free shipping on all orders</div>