HTML & CSS

Migrate WebKit Linear Gradients to Standard CSS

Replace legacy WebKit gradient syntax carefully: convert starting-side keywords and angles, preserve color stops, and compare the modern CSS at multiple sizes.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Identify which WebKit gradient syntax you have

For a new stylesheet, use the standard linear-gradient() function. When maintaining older CSS, first distinguish -webkit-linear-gradient(...) from the still older -webkit-gradient(linear, ...). They are different syntaxes. Removing the prefix from either string without examining its arguments can change the result or leave an invalid declaration.

WebKit’s 2011 gradient introduction is useful historical documentation for the prefixed linear form. Its direction keyword names the starting side, and its old angle convention differs from the standard convention. Treat that article as an explanation of existing code, not a recommendation to author new prefixed declarations.

Convert the direction while keeping the colors

In the legacy expression below, the first color begins on the left. The standard expression points toward the right. The colors remain in their original order. Reversing the colors as well as reversing the direction would make a second change and undo the intended mapping.

/* Legacy starting-side syntax */
.legacy-side {
  background-image: -webkit-linear-gradient(left, #123456, #abcdef);
}
/* Standard destination-side syntax */
.modern-side {
  background-image: linear-gradient(to right, #123456, #abcdef);
}

The same reasoning maps an old top keyword to to bottom, and an old bottom right starting corner to to top left. Compare a wide rectangle as well as a square when migrating corner keywords. A square alone can hide differences in how a diagonal relates to the painted box.

For the historical numeric-angle convention, convert the angle to 90 degrees minus the old angle, then normalize to a full turn if desired. Old 0deg maps to standard 90deg; old 90deg maps to standard 0deg; old 135deg maps to standard 315deg. Do not use this conversion on values that are already standard CSS angles.

.legacy-angle {
  background-image: -webkit-linear-gradient(135deg, #123456, #abcdef);
}
.modern-angle {
  background-image: linear-gradient(315deg, #123456, #abcdef);
}

Handle the older two-point function separately

The older -webkit-gradient() form specifies endpoints and wraps stops in functions such as from(), to() and color-stop(). WebKit’s 2008 article now labels that syntax deprecated. A straightforward full-height vertical example can be rewritten as follows.

.legacy-points {
  background-image: -webkit-gradient(linear, left top, left bottom,
    from(#123456), color-stop(.4, #52789a), to(#abcdef));
}
.modern-points {
  background-image: linear-gradient(to bottom,
    #123456 0%, #52789a 40%, #abcdef 100%);
}

Do not generalize that example into a blind replacement for arbitrary endpoints. A legacy gradient whose endpoints occupy only part of the element may need different stop positions, sizing or positioning to reproduce its geometry. Preserve a screenshot and the original declaration before adjusting such a case.

Keep migration separate from unrelated cleanup

Search the actual source stylesheets and build configuration before editing a generated minified file. If a build tool adds prefixes, change the maintained source and browser targets instead of patching each emitted declaration by hand. Rebuilding should reproduce the migration rather than restore the old code.

When a documented legacy-browser requirement still needs a prefixed fallback, place it before the standard declaration and test both environments. Do not retain three different gradient generations merely because an old tutorial listed them. The project’s browser support policy should decide which compatibility paths remain necessary.

Compare controlled examples before and after

Give the old and new swatches identical dimensions, background sizing and color stops. Compare the start and end corners, then inspect the middle transition. Change the box from a wide rectangle to a tall one and repeat. A mismatch only at the ends often points to an angle or keyword conversion error.

Also inspect the complete component in context. A later background shorthand can reset your corrected background-image, while a more specific selector can override it entirely. Confirm the winning declaration in developer tools rather than assuming that a successful text replacement changed what the browser paints.

Use the generator for new standard declarations

The CSS Gradient Generator produces unprefixed linear, radial and conic backgrounds. For a two-color replacement, choose Linear, enter the converted standard angle and select the two original opaque colors. The tool does not parse legacy syntax or translate arbitrary endpoint-based gradients.

Keep manually positioned intermediate stops in your stylesheet: the generator has only two color controls. After migration, preserve the original URL and class hooks used by your application, remove obsolete duplicate declarations only after testing, and record any legacy browser dependency that prevented full cleanup.