How to Create Cross-Browser CSS Gradients
Create CSS gradients with standard syntax, choose directions and color stops, and handle browser support and legacy prefixes.
For most projects, create a cross-browser CSS gradient with the standard, unprefixed linear-gradient() function, then check the exact syntax against the browsers your project supports. Basic linear gradients are widely available, but newer gradient features can have different support. Add vendor-prefixed forms only when your support policy requires a specific legacy browser.
.hero {
background: linear-gradient(to right, #17324d, #68b5a7);
}This creates an image that transitions between two color stops. The CSS gradient syntax and its browser behavior are documented in MDN’s linear-gradient() reference. For a screenshot of how a gradient renders on a page, ScreenshotNeo can capture a URL as an image or PDF.
1. Write the standard gradient
A linear gradient is a CSS image produced from at least two color stops. You can use it anywhere CSS accepts an image, including background and background-image. It is not a color value, so it does not belong in background-color.
.card {
background-image: linear-gradient(#17324d, #68b5a7);
}If you omit the direction, the gradient runs from top to bottom. The gradient has no intrinsic dimensions of its own; it is painted to fit the element’s background area. Give the element a size or content if you need a visible area to inspect.
2. Choose a direction and place color stops
You can specify a side or corner with to, or provide an angle. Add stop positions to control where each color appears. Without a position, the browser distributes stops across the gradient.
.banner {
background: linear-gradient(135deg, #17324d 0%, #376f82 55%, #68b5a7 100%);
}
.sidebar {
background: linear-gradient(to bottom right, #17324d, #68b5a7);
}
.callout {
background: linear-gradient(90deg, #17324d, #68b5a7);
}| Syntax | Effect |
|---|---|
to right |
Runs toward the right side. |
to bottom left |
Runs toward the bottom-left corner. |
0deg |
Runs from bottom to top. |
90deg |
Runs from left to right. |
135deg |
Runs diagonally; useful when the direction should be independent of named sides. |
Angles can be easy to misread: 0deg is bottom-to-top, not top-to-bottom. Use a named side when it makes the intended direction clearer. Add intermediate stops for more control, and check that stop positions are in the order and range you intend.
3. Check support for the syntax you actually use
CSS gradients are broadly available across browsers. MDN describes the gradient type as widely available since July 2015, while noting that support can vary for some parts of the syntax. That broad statement does not guarantee support for every newer feature, such as a particular color interpolation method.
- Read the browser support policy for your site or application. Identify the browser names and minimum versions it promises to support.
- Check the exact gradient feature you plan to use against current compatibility data for those targets. Check newer interpolation syntax separately from basic
linear-gradient(). - Use the standard syntax in your source CSS. If the feature is unsupported by a required browser, choose a supported alternative or provide a fallback.
- Review the rendered result in the browser versions that matter to your project.
Do not infer a universal version floor from a general statement that gradients are widely available. Your browser list and the exact syntax determine the compatibility decision.
4. Add prefixes only for a defined legacy requirement
For ordinary modern projects, start with unprefixed CSS. Vendor prefixes reflect older browser implementations and are not a general cross-browser recipe. MDN’s CSS FAQ advises against routine production use of prefixed properties, while its Mozilla extensions reference recommends linear-gradient() in place of -moz-linear-gradient.
Use a prefix only after identifying a browser in your support policy that needs it, and verify the precise syntax for that browser. For historical context, earlier Safari versions used -webkit-gradient(); -webkit-linear-gradient() support arrived in Safari 5.1 and iOS 5.0. Those old forms are not a recommendation to support those releases today. See Apple’s archived Safari gradient guide.
When a legacy prefix is required, place the prefixed declaration first and the standard declaration after it so browsers that understand the standard form can use it:
.legacy-banner {
background: -webkit-linear-gradient(left, #17324d, #68b5a7);
background: linear-gradient(to right, #17324d, #68b5a7);
}Treat this as a targeted compatibility measure, not a list to copy into every stylesheet. Older prefixed syntaxes can differ, so confirm the required form for the specific browser rather than assuming all prefixes are interchangeable.
5. Let Autoprefixer follow your browser policy
If your project has a CSS build pipeline, configure its browser targets with Browserslist and use Autoprefixer to generate prefixes where its data says they are needed. Keep standard CSS in your source and inspect the generated output when changing browser targets.
{
"browserslist": [
"defaults"
]
}The example target above is illustrative. Set targets that match your project’s actual support policy; a generic target is not a substitute for deciding which browsers you support.
.hero {
background: linear-gradient(to right, #17324d, #68b5a7);
}Autoprefixer uses Browserslist targets to decide which prefixes to add. It adds prefixes; it does not polyfill unsupported CSS features. It also may not transform input that contains only the legacy -webkit-gradient() syntax, because it needs standard source syntax to work from. Read the Autoprefixer documentation and Browserslist documentation for configuration details.
6. Handle common mistakes and failures
| Symptom | Likely cause | Fix |
|---|---|---|
| The background is a solid color or appears missing. | The gradient was assigned to background-color, the element has no visible area, or the declaration has a syntax error. |
Use background or background-image, give the element visible dimensions, and check the function’s parentheses and comma-separated stops. |
| The gradient runs in the opposite direction. | The angle convention was misunderstood. | Remember that 0deg runs bottom-to-top and 90deg runs left-to-right; use to right or another named direction if clearer. |
| A required older browser does not show the expected gradient. | The browser may need a legacy syntax or may not support the feature used. | Identify the browser floor, check the exact syntax, and add only the fallback required by that target. Test the fallback in that browser. |
| Autoprefixer emits no prefix. | The configured targets may not require one, or the source is not standard gradient syntax. | Review the Browserslist targets and keep unprefixed linear-gradient() in source. Do not expect Autoprefixer to convert every legacy-only form. |
| A basic gradient works, but a newer gradient effect does not. | Support for newer syntax can differ from support for the basic function. | Check compatibility for that exact feature and supply an alternative or fallback if your required browsers need it. |
7. Keep the CSS reliable and maintainable
- Keep the standard gradient declaration in source so it remains readable and build tools can analyze it.
- Use the project’s documented browser targets as the source of truth; revisit them when the support policy changes.
- Keep fallbacks focused on the browser or syntax limitation they address. Avoid duplicating old prefixes without an identified need.
- For a critical visual, include a suitable solid background color before the gradient as a basic fallback for environments that cannot render the image.
.hero {
background-color: #17324d;
background-image: linear-gradient(to right, #17324d, #68b5a7);
}The solid color declaration provides a simple background if the image-valued declaration is not supported. It does not recreate the gradient, but it avoids relying on the gradient for all visual context.
8. See the rendered gradient in a page screenshot
CSS compatibility is about rendering in the browsers your project targets. If you need to inspect a deployed page or compare a visual change, capture the page after the CSS is applied. A screenshot can help review the result, but it does not replace checking the actual browser and version requirements.
Or skip the browser setup
ScreenshotNeo returns a screenshot or PDF from one API request. See the ScreenshotNeo API docs for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);Replace the example URL with your page and use your API key. ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
Frequently asked questions
Do I need a vendor prefix for every gradient?
No. Use standard, unprefixed syntax by default. Add a prefix only when a specific browser in your support policy requires it.
Can I use a gradient as a text or border color?
A gradient is an image, so it works in image-valued properties. It is not itself a color value; techniques for text or borders need to use the relevant image-capable CSS property.
Does Autoprefixer make unsupported gradient features work?
No. It adds prefixes based on configured browser targets; it is not a polyfill for unsupported CSS features.
What should I check when using a newer gradient syntax?
Check compatibility for that exact syntax against the browsers and minimum versions your project supports. Basic gradient support does not establish support for every newer option.
