03-mastering-css3-gradient-syntax
# A Guide to Mastering Complex CSS3 Gradient Syntax
CSS gradients have been production-stable since CSS3, but most codebases use only a fraction of the available syntax. Two-stop linear-gradient declarations cover the common cases, but complex design work, mesh-like backgrounds, conical sweeps, hard-edged stripe patterns, perceptually smooth color transitions, requires a deeper understanding of the full specification. This guide covers the complete syntax across all three gradient functions, with code examples that demonstrate the less-used features practitioners encounter when replicating production designs.
The Three Gradient Functions
CSS provides three main gradient functions:
linear-gradient(), color stops along a straight line at a specified angleradial-gradient(), color stops radiating outward from a focal pointconic-gradient(), color stops sweeping around a center point in an arc
Each has a repeating- variant (repeating-linear-gradient, repeating-radial-gradient, repeating-conic-gradient) that tiles the gradient pattern across the element.
Linear Gradient: Full Syntax
linear-gradient( [ <angle> | to <side-or-corner> ], <color-stop-list> )Angle Values
The angle controls the direction of the gradient line. 0deg is upward (toward the top edge); values increase clockwise.
/* Equivalent: both render a top-to-bottom gradient */
background: linear-gradient(180deg, #1a1a2e, #e94560);
background: linear-gradient(to bottom, #1a1a2e, #e94560);
/* 45-degree diagonal */
background: linear-gradient(45deg, #1a1a2e, #e94560);
/* Precise non-cardinal angle */
background: linear-gradient(112.5deg, #0f0c29, #302b63, #24243e);When replicating a gradient extracted from an image using a tool like Gradient Scanner, the angle output will typically be in degrees rather than directional keywords, which is the more precise form.
Color Stop Positions
Stop positions can be expressed as percentages, absolute lengths, or omitted entirely (the browser distributes them evenly).
/* Evenly distributed, browser calculates positions */
background: linear-gradient(to right, #f7971e, #ffd200, #f7971e);
/* Explicit percentage positions */
background: linear-gradient(
to right,
#f7971e 0%,
#ffd200 30%, /* skewed toward the left */
#f7971e 100%
);
/* Absolute length positions */
background: linear-gradient(
to right,
#1a1a2e 0px,
#e94560 200px
);Color Hints (Midpoint Adjustment)
A single value between two color stops, with no color attached, is a color hint. It shifts the midpoint of the interpolation without adding a new discrete stop.
/* Default midpoint at 50% between stops */
background: linear-gradient(to right, #1a1a2e, #e94560);
/* Midpoint shifted to 25%, transition accelerates sooner */
background: linear-gradient(to right, #1a1a2e, 25%, #e94560);Color hints are useful when replicating gradients that appear to ease in or out, rather than progressing linearly. They are one of the first tools to reach for when a two-stop CSS gradient does not match the original design.
Hard Stops (Stripe Patterns)
When two consecutive stops share the same position, the transition is instantaneous, producing a hard edge. This enables stripe patterns without any image assets:
/* Three equal stripes */
background: linear-gradient(
to right,
#e94560 0%, #e94560 33.33%,
#0f3460 33.33%, #0f3460 66.66%,
#16213e 66.66%, #16213e 100%
);
/* Diagonal stripes using repeating variant */
background: repeating-linear-gradient(
45deg,
#1a1a2e,
#1a1a2e 10px,
#16213e 10px,
#16213e 20px
);Radial Gradient: Full Syntax
radial-gradient( [ <ending-shape> || <size> ] [ at <position> ]?, <color-stop-list> )Shape and Size
The ending shape is either circle or ellipse. If omitted, the browser infers the shape from the element's aspect ratio.
The size keyword controls how far the gradient extends:
closest-side, stops at the nearest edge of the boxfarthest-side, extends to the farthest edgeclosest-corner, stops at the nearest cornerfarthest-corner, extends to the farthest corner (the default)
/* Circle contained within the nearest edge */
background: radial-gradient(circle closest-side at 50% 50%, #fc5c7d, #6a82fb);
/* Ellipse at a custom position */
background: radial-gradient(ellipse farthest-corner at 20% 30%, #4facfe 0%, #00f2fe 100%);Explicit Size Values
Instead of keywords, you can provide explicit size values:
/* Circle with a fixed 200px radius */
background: radial-gradient(circle 200px at center, #f7971e, transparent);
/* Ellipse with explicit horizontal and vertical radii */
background: radial-gradient(ellipse 60% 40% at 50% 50%, #302b63, #0f0c29);This level of control is important when replicating extracted gradients where the focal point and falloff are precisely defined.
Conic Gradient: Full Syntax
conic-gradient( [ from <angle> ]? [ at <position> ]?, <color-stop-list> )conic-gradient sweeps color stops around a center point. The stops are placed at angular positions rather than linear or radial distances.
/* Simple two-color sweep starting from the top */
background: conic-gradient(from 0deg, #fc5c7d, #6a82fb, #fc5c7d);
/* Pie chart approximation */
background: conic-gradient(
#e94560 0deg 120deg,
#0f3460 120deg 240deg,
#16213e 240deg 360deg
);
/* Hard-stop pie with center offset */
background: conic-gradient(
from 90deg at 40% 60%,
#f7971e 0deg 90deg,
#ffd200 90deg 180deg,
#f7971e 180deg 360deg
);Color Interpolation Color Spaces
Modern browsers support the in <colorspace> syntax for controlling how the browser interpolates between stops. This is a significant addition that affects perceived gradient smoothness.
/* Default sRGB interpolation (can produce grey muddy midpoints) */
background: linear-gradient(to right, hsl(0 100% 50%), hsl(240 100% 50%));
/* OKLCH interpolation, perceptually uniform, avoids grey midpoints */
background: linear-gradient(in oklch to right, hsl(0 100% 50%), hsl(240 100% 50%));
/* Display-p3 for wide-gamut displays */
background: linear-gradient(in display-p3 to right, #ff0000, #0000ff);OKLCH interpolation is the most practically useful option. It prevents the washed-out grey band that commonly appears at the midpoint of high-saturation complementary color gradients. When replicating a gradient from an image that looks vivid across its full range, switching to oklch interpolation is often the fix if a straight sRGB interpolation looks dull.
Layering Multiple Gradients
The background property accepts a comma-separated list of layers, painted from top to bottom. This enables multi-layer gradient compositions without pseudo-elements:
.mesh-bg {
background:
radial-gradient(ellipse at 20% 20%, rgba(249, 115, 22, 0.4) 0%, transparent 60%),
radial-gradient(ellipse at 80% 80%, rgba(99, 102, 241, 0.4) 0%, transparent 60%),
radial-gradient(ellipse at 50% 50%, rgba(16, 185, 129, 0.3) 0%, transparent 70%),
#0f0c29;
}The final value (#0f0c29) is a solid color fallback that shows through all transparent regions.
Practical Reference: Extracting Angles from Image Gradients
When working backward from a design file or screenshot, the angle is the hardest value to determine visually. The relationship between degree value and visual direction follows this convention:
| Degree | Visual Direction | |----|---------| | 0deg | Bottom to top | | 45deg | Bottom-left to top-right | | 90deg | Left to right | | 135deg | Top-left to bottom-right | | 180deg | Top to bottom |
Tools like Gradient Scanner compute the angle automatically from the traced path across an image, which eliminates guesswork when the gradient is at a non-standard angle.
Summary
The full CSS gradient specification supports hard stops, color hints, explicit focal geometries, size keywords, angular sweeps, multi-layer compositions, and perceptually uniform color space interpolation. Each feature addresses a specific class of design, from striped patterns to mesh backgrounds to vivid complementary transitions. Knowing which tool applies to which problem is what separates a maintainable, image-free stylesheet from one that reaches for a PNG every time the design gets complex.