CSS Gradient Syntax: Complete Code Guide for Linear and Radial

CSS gradient syntax can feel confusing at first, but once you understand the pieces, you can read and write gradient code confidently. Whether you're hand-coding gradients or copying them from a generator, knowing the syntax helps you tweak, optimize, and combine gradients with other CSS properties. This guide breaks down every part of linear and radial gradient syntax so you can write them correctly from the start.

Understanding the Basic Gradient Structure

All CSS gradients follow a similar pattern. You use the background or background-image property and call a gradient function. The gradient function contains the type, direction, colors, and positions.

Here's the general structure:

background: gradient-type(direction, color1 position1, color2 position2);

For a real example:

background: linear-gradient(90deg, #3b82f6 0%, #ec4899 100%);

This sets a linear gradient that moves 90 degrees (left to right), starting with blue and ending with pink. The two colors have explicit positions at 0% and 100%, meaning blue is at the start and pink is at the end.

You don't always need to write positions. If you skip them, the browser spaces colors evenly:

background: linear-gradient(90deg, #3b82f6, #ec4899);

This works the same way, but the color stops are implicit. The browser automatically places the first color at 0% and the last at 100%.

Linear Gradient Syntax Breakdown

A linear gradient moves color along a straight line. The syntax is:

background: linear-gradient(direction, color-stop-1, color-stop-2, ...);

Direction: Angles and Keywords

The direction controls which way the gradient flows. You can use either angles or keywords.

Angle values range from 0 to 360 degrees:

  • 0deg — color flows from bottom to top (upward)
  • 90deg — color flows from left to right (horizontal)
  • 180deg — color flows from top to bottom (downward)
  • 270deg — color flows from right to left (backward)
  • 45deg — diagonal from bottom-left to top-right
  • 135deg — diagonal from top-left to bottom-right

The angle starts at the bottom and goes clockwise. This trips up many people because they expect 0 degrees to point right (like in math), but in CSS gradients it points up.

Keyword values are alternatives to angles:

  • to top — same as 0deg
  • to right — same as 90deg
  • to bottom — same as 180deg
  • to left — same as 270deg
  • to top right — same as 45deg
  • to bottom right — same as 135deg
  • to bottom left — same as 225deg
  • to top left — same as 315deg

Keywords are readable, but angles are more flexible if you need odd directions like 17deg or 203deg.

Color Stops: Colors and Positions

Color stops define what color appears and where. A color stop has two parts: the color value and the position.

background: linear-gradient(90deg, #3b82f6 25%, #ec4899 75%);

Here, blue appears at 25% and pink appears at 75%. The gradient transitions smoothly between them.

Position units:

  • Percentages (0%, 50%, 100%) are the most common. They define where the color sits relative to the gradient line.
  • Absolute lengths (10px, 2em, 1cm) work too, but they're less common and less predictable because the length depends on the element's size.

If you don't write a position, the browser spaces colors evenly. With three colors and no positions, they sit at 0%, 50%, and 100%:

background: linear-gradient(90deg, #3b82f6, #ec4899, #10b981);

You can also let the browser figure out some positions. If you skip the position on the middle color, it sits halfway between the colors before and after:

background: linear-gradient(90deg, #3b82f6 0%, #ec4899, #10b981 100%);

The pink here sits at 50%.

Repeating Linear Gradients

A normal linear gradient fills the entire element. A repeating linear gradient tiles the gradient pattern across the element like a stripe or checkerboard.

background: repeating-linear-gradient(90deg, #3b82f6 0px, #3b82f6 20px, #ec4899 20px, #ec4899 40px);

This creates vertical stripes: 20 pixels of blue, then 20 pixels of pink, repeating. With repeating gradients, use absolute lengths (not percentages) for more control.

You can use it for decorative borders, stripe patterns, progress bars, or visual separators without needing an image file.

Radial Gradient Syntax Breakdown

Radial gradients spread outward from a center point. The syntax is different from linear gradients because you control the center position, shape, and size instead of direction.

background: radial-gradient(shape size at position, color-stop-1, color-stop-2, ...);

Shape: Circle or Ellipse

The shape determines whether the gradient spreads as a circle or an ellipse (oval).

  • circle — colors spread outward equally in all directions
  • ellipse — colors spread outward in an oval shape, following the element's width and height
background: radial-gradient(circle, #3b82f6 0%, #ec4899 100%);

This is a circular gradient centered in the element, with blue at the center and pink at the edges.

background: radial-gradient(ellipse, #3b82f6 0%, #ec4899 100%);

This is an oval gradient that stretches to match the element's aspect ratio.

If you don't write a shape, the browser assumes ellipse.

Size Keywords

You can control how large the gradient gets. These keywords define the radius:

  • closest-side — the gradient extends to the nearest edge of the element
  • farthest-side — the gradient extends to the farthest edge
  • closest-corner — the gradient reaches the nearest corner
  • farthest-corner — the gradient reaches the farthest corner (default)
background: radial-gradient(circle closest-side, #3b82f6 0%, #ec4899 100%);

The gradient here stops at the nearest edge, so it doesn't fill the whole element.

background: radial-gradient(circle farthest-corner, #3b82f6 0%, #ec4899 100%);

The gradient here extends all the way to the farthest corner, fully filling the element.

Position: Moving the Center

By default, the gradient's center sits at 50% 50% (the element's center). You can move it using the at keyword.

background: radial-gradient(circle at 30% 70%, #3b82f6 0%, #ec4899 100%);

This moves the gradient's center to 30% from the left and 70% from the top. The blue glow now appears in the bottom-left area.

You can use percentages or absolute lengths:

background: radial-gradient(circle at 100px 200px, #3b82f6 0%, #ec4899 100%);

This places the center 100 pixels from the left and 200 pixels from the top.

Repeating Radial Gradients

Like linear gradients, you can create a repeating radial gradient for rings or circular patterns.

background: repeating-radial-gradient(circle, #3b82f6 0px, #3b82f6 20px, #ec4899 20px, #ec4899 40px);

This creates concentric rings: 20 pixels of blue, then 20 pixels of pink, repeating outward from the center.

Advanced Syntax: Color Hints

A color hint is a position between two color stops that controls how they blend. It's useful when the midpoint between two colors doesn't look right.

background: linear-gradient(90deg, #3b82f6 0%, 30%, #ec4899 100%);

The 30% here is a color hint. It shifts where the blue and pink meet. Without the hint, they'd meet at 50%. With it, they meet closer to 30%, so blue dominates more.

Color hints are subtle but powerful for fine-tuning gradients without adding extra color stops.

Combining Gradients with Other Properties

Gradients work best when combined with other CSS properties. Here are some practical examples.

Gradients with Background Size

You can layer multiple gradients or combine a gradient with a background image by using background-image:

background-image: 
  linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(236, 72, 153, 0.8)),
  url('/image.jpg');
background-size: cover, cover;
background-position: center, center;

The gradient sits on top of the image. The rgba() colors include transparency so the image shows through.

Gradients with Transitions

You can animate a gradient change using CSS transitions. Gradients respond to state changes like hover:

.button {
  background: linear-gradient(90deg, #3b82f6 0%, #2563eb 100%);
  transition: background 0.3s ease;
}

.button:hover {
  background: linear-gradient(90deg, #2563eb 0%, #1d4ed8 100%);
}

The gradient smoothly shifts when you hover, creating a subtle but noticeable effect.

Gradients with Box Shadow

Combine a gradient with a box shadow for depth:

.card {
  background: linear-gradient(135deg, #f3f4f6 0%, #e5e7eb 100%);
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
}

The gradient provides the base color blend, and the shadow adds dimension.

Common Syntax Mistakes to Avoid

Missing the Gradient Function

This won't work:

background: 90deg, #3b82f6, #ec4899;

You must include the function name:

background: linear-gradient(90deg, #3b82f6, #ec4899);

Wrong Angle Direction Assumption

Many people expect 0deg to point right (like a compass or math angle), but in CSS it points up:

/* This is UPWARD, not rightward */
background: linear-gradient(0deg, #3b82f6, #ec4899);

/* This is RIGHTWARD */
background: linear-gradient(90deg, #3b82f6, #ec4899);

Forgetting the at Keyword for Radial Position

This syntax is wrong:

background: radial-gradient(circle 30% 70%, #3b82f6, #ec4899);

Add at:

background: radial-gradient(circle at 30% 70%, #3b82f6, #ec4899);

Using Percentages Instead of Pixels in Repeating Gradients

Percentages don't work well with repeating gradients:

/* Problematic — the repetition pattern is unclear */
background: repeating-linear-gradient(90deg, #3b82f6 0%, #3b82f6 50%, #ec4899 50%, #ec4899 100%);

/* Better — clear repetition every 40 pixels */
background: repeating-linear-gradient(90deg, #3b82f6 0px, #3b82f6 20px, #ec4899 20px, #ec4899 40px);

Using a Gradient Generator to Learn Syntax

If you're not comfortable hand-writing gradients yet, a CSS gradient generator lets you build gradients visually and see the syntax as you go. You can pick colors, adjust angles and positions, and copy the exact code. Over time, reading the generated code teaches you the syntax naturally, and you'll start writing gradients from scratch.

The generator is also useful for testing syntax ideas. If you write a gradient line and it doesn't work, paste it into the generator and adjust visually until it looks right, then read what changed.

Testing Your Gradient Syntax

After you write a gradient, test it in different browsers. Most modern browsers support linear and radial gradients, but some older or less common browsers might not. You can check browser support on caniuse.com.

For maximum compatibility, consider adding a fallback solid color:

background: #3b82f6; /* fallback */
background: linear-gradient(90deg, #3b82f6, #ec4899);

If the gradient doesn't render, the browser falls back to the solid blue.

You should also test your gradient in context. Paste it into your actual HTML and view it on the page, on mobile, and in different light settings. A gradient that looks perfect in an editor can feel different on the actual site.

Next Steps with Gradients

Now that you understand the syntax, you can read gradients from other projects and modify them to fit your design. You can adjust angles, add color stops, change positions, and even combine multiple gradients.

Start simple: take a two-color linear gradient, change the angle, and see how it affects the look. Add a third color stop. Try a radial gradient with an offset center. The more you experiment, the faster the syntax becomes second nature.

CSS gradient syntax is not as scary as it looks. Once you know that angles control direction, color stops define colors and positions, and at moves a radial gradient's center, you can write any gradient you need. Practice with the gradient generator, experiment with variations, and soon you'll be writing gradients confidently without looking up the syntax every time.