Gradient Generator

Starting from the center of the gradient box, extend a line at the specified angle in both directions. The ending point sits where a line drawn perpendicular to the gradient line intersects the corner of the gradient box in the specified direction. To determine the starting point, apply this exact same logic in the opposite direction.

NOTE:

It is expected that the next level of this module will provide the ability to define the gradient’s direction relative to the current text direction and writing-mode.

Example 3

This example illustrates visually how a browser calculates the gradient line using the rules above. Both the starting and ending points appear on the map alongside the final gradient image to clarify this behavior. Ultimately, an element executing the style rule background: linear-gradient(45deg, white, black); produces this exact visual layout

Notice how the browser positions the starting and ending points outside of the element’s box boundary. Remarkably, the rendering engine aligns these markers so precisely that the gradient shifts to pure white exactly at one corner and pure black exactly at the opposite corner.

GIVEN:

• A the angle (in any quadrant) defining the gradient line’s direction such that 0 degrees points upwards and positive angles represent clockwise rotation,
• W the width of the gradient box,
• H the height of the gradient box,

The length of the gradient line (between the starting point and ending point) is:

abs(W * sin(A)) + abs(H * cos(A))

Typically, browsers place a gradient’s color-stops along the gradient line between the starting and ending points. However, the rendering engine does not require this specific boundary because the gradient line extends infinitely in both directions. Functionally, the starting and ending points serve merely as arbitrary location markers. Specifically, the starting point defines the baseline location for values like 0% or 0px, while the ending point marks the location for 100%. Consequently, developers can freely assign color-stop positions that fall before 0% or after 100%.

position

Determines the center of the gradient. The value type (which is also used for background-position) is defined in [CSS-VALUES-3], and is resolved using the center-point as the object area and the gradient box as the positioning area. If this argument is omitted, it defaults to center.

radial-shape

The <radial-shape> can be defined as either circle or ellipse to determine whether the browser draws a circular or elliptical gradient. If the developer omits this property, the rendering engine defaults the ending shape to a circle, provided that the <radial-size> contains a single <length> value. Otherwise, the rendering engine automatically defaults the final configuration to an ellipse

radial-size

First, this parameter determines the size of the gradient’s ending shape. If the developer omits this value, the system defaults the size to farthest-corner. To define this size, developers can use either explicit values or specific keywords. Furthermore, keyword definitions require the system to treat the gradient box edges as infinite lines rather than finite line segments.

Whenever the ending shape forms an ellipse, its dimensions align perfectly with the horizontal and vertical orientations.

closest-side

Specifically, the system sizes the ending shape so that it exactly meets the side of the gradient box closest to the gradient’s center. If the shape forms an ellipse, it must exactly meet the closest side in both the horizontal and vertical dimensions.

farthest-size

This keyword operates identically to closest-side. However, the system sizes the ending shape based on the farthest side or sides, rather than the closest.

closest-corner

The system sizes the ending shape so that it passes through the corner of the gradient box closest to the gradient’s center. Furthermore, if the shape forms an ellipse, the system assigns it the exact same aspect ratio it would receive under the closest-side specification

farthest-corner

This keyword operates identically to closest-corner. However, the system sizes the ending shape based on the farthest corner instead of the closest. Elliptical shapes will also adopt the exact same aspect ratio they would receive under the farthest-side specification.

Placing Color Stops

Color-stops are placed on a ray-shaped gradient line. This ray originates at the center of the gradient and extends infinitely to the right, matching the behavior of linear gradients. Its ending point is established at the exact intersection with the ending shape.

Furthermore, developers can place a color-stop before 0%. Even though rendering engines never directly consult this negative region, these stops still matter. Through interpolation or repetition, they actively alter the color of non-negative locations.

Radial Gradient Examples

All of the following examples are applied to a box that is 200px wide and 100px tall.

Example 5

These examples demonstrate different ways to write the basic syntax for radial gradients:

• radial-gradient(5em circle at top left, yellow, blue)
• radial-gradient(5em circle at top left, yellow, blue)
• radial-gradient(5em circle at top left, yellow, blue)

radial-gradient(circle, yellow, green);

radial-gradient(circle, yellow, green);

Example 5

This image shows a gradient originating from somewhere other than the center of the box:

• radial-gradient(farthest-side at left bottom, red, yellow 50px, green);

Example 5

Here we illustrate a closest-side gradient.

• radial-gradient(closest-side at 20px 30px, red, yellow, green);
• radial-gradient(20px 30px at 20px 30px, red, yellow, green);

• radial-gradient(closest-side circle at 20px 30px, red, yellow, green);
• radial-gradient(20px 20px at 20px 30px, red, yellow, green);

Repeating Gradients: the repeating-linear-gradient() and repeating-radial-gradient() notations

In addition to linear-gradient() and radial-gradient(), this specification defines repeating-linear-gradient() and repeating-radial-gradient() values. These notations take the same values and are interpreted the same as their respective non-repeating siblings defined previously.

< repeating-linear-gradient() > = repeating-linear-gradient( [ linear-gradient-syntax ] )

< repeating-radial-gradient() > = repeating-radial-gradient( [ radial-gradient-syntax ] )

Rendering

During rendering, color-stops repeat infinitely in both directions. Multiples of the difference between the final and initial positions dictate how these points shift. To illustrate this, repeating-linear-gradient(red 10px, blue 50px) matches linear-gradient(…, red -30px, blue 10px, red 10px, blue 50px, red 50px, blue 90px, …). Sharp transitions occur because the last and first color-stops always meet at the boundary of each group, unless the gradient starts and ends with the identical color.

Example 6

Repeating gradient syntax is identical to that of non-repeating gradients:

• repeating-linear-gradient(red, blue 20px, red 40px)

• repeating-radial-gradient(red, blue 20px, red 40px)

• repeating-radial-gradient(circle closest-side at 20px 30px, red, yellow, green 100%, yellow 150%, red 200%)

Average Color Fallback

If a tiny, non-zero distance separates the first and last color-stops, the output device may lack the physical resolution to faithfully render the gradient. In this scenario, the implementation must calculate the average color of the gradient. Consequently, the system must render a solid-color image using that calculated average.

Handling Zero-Length Gradients

The system must create a temporary reference gradient whenever the distance between the first and last color-stops equals zero (or rounds to zero due to implementation limits). To do this, the software separates the first and last color-stops by an arbitrary non-zero distance while spacing the remaining stops equally between them. Calculating the average color of this new gradient configuration serves as the next step. Ultimately, the engine renders a solid-color image using that exact average.

Rendering Zero-Height Radial Gradients

Whenever a repeating radial gradient has a non-zero width but a height of zero, the device may struggle to display it. Similarly, the same problem occurs if the height drops so close to zero that the output device lacks the physical resolution to faithfully render the gradient. In either scenario, the implementation calculates the average color of the gradient. The system then uses this calculated average to render a solid-color image.