The radial-gradient() function is used to create a <radial-gradient> object, which represents a texture consisting of a transition between two or more colors radiating out from a defined point. The <radial-gradient> object is a type of <paint>, which can be used to color backgrounds, text and borders.

Required and Optional Parameters:

A basic radial gradient requires that developers define these parameters

ParameterDescriptionValue
Gradient radiusThe overall size of the gradient as it radiates out. The final color stop is applied outside the radius if no gradient cycling is applied.<size>
Color stopsThe colors associated with the gradient, starting closest to the center and iterating outwards<color>

Additionally, developers may further customise their gradients with several optional parameters

ParameterDescriptionValue
focus-distanceThe radial distance between the geometric center of the gradient and the color center. An opportunity to move the position of the start color towards the outer edge of the radius. Values are clamped between 0 and 100%
Default: zero
<percentage>
focus-angleThe radial angle between the geometric center of the gradient and the color center. Must be defined in parallel with focus-distance.
Default: zero
<angle>
centerThe geometric center of the radial gradient. When the focus-distance is zero, this is also the color-center of the gradient.
Default: 0, 0
<point>
cyclingThe behaviour of the gradient outside the radius. If undefined, the colour outside the radius will equal the final color stop. If defined, the color will cycle through the color stops in the defined way indefinitely.
Values: reflect | repeat
Default: none
<point>

Parameter definition

In the following sections, the required and optional parameters are defined in detail. Please note the limitations on units documented for both defining the geometry of the gradient (radius and center) and the color stops.

1. Radius

The radius parameter should be defined as a <size>, which can be in absolute (length) or proportional (percentage) units (see the documentation for <size>).

If no unit is defined, absolute units in pixels is assumed.

Note: As well as impacting the size of the gradient, this will have significant impact on the shape of the gradient.

A Limitations on defining units

Currently, the choice between absolute and proportional units must be consistent between the radius and center parameters. This includes if the either are defined in the absence of units (e.g. “radius 80”), in which case the default units are pixels.

Absolute center with proportional radius:
The radius is assumed to be 0 and the entire texture is rendered at the color of the final color stop.

Absolute radius with proportional center:
The center is assumed to be {0,0} and the gradient radiates from the top left corner as if the center had not been defined.

> Radius using Proportional units

If proportional units are used, the gradient shape will be in proportion to the container. For example, a circular gradient will be created in a square container and an elliptical gradient will be created in a rectangular container when a value of 50% is used to define the radius.

-fx-background-color: radial-gradient(radius 50%, red, blue);
> Radius using Absolute units

If absolute units are used, the gradient shape will not be in proportion to the container. For example, a circular gradient will be created in a square container and a rectangular container when a value of 50px is used to define the radius.

-fx-background-color: radial-gradient(radius 50px, red, blue);

2. Center

By default, the gradient will radiate from the top left corner of the container. This behaviour can be modified by adding a positional parameter to define the center of the gradient to be created.

Please see the detailed note above (see ‘radius’) on the limitations of units for this parameter

> Absolute Dimensions
-fx-background-color: radial-gradient(center 50px 50px, 
radius 100px, red, blue);
radial-gradient(center 50px 50px,
radius 50px, red, blue);
> Proportional Dimensions
-fx-background-color: radial-gradient(center 50% 50%, 
radius 50%, red, blue);
radial-gradient(center 50% 50%,
radius 50%, red, blue);

3. Multiple Color Stops

Color stops can be defined with or without a position, although the color-stops must follow these rules:

  • <length> color stop positions do not appear to be supported for the radial-gradient() function.
  • If no positions are provided, color stops are distributed evenly between 0 and 100% (proportional to the size of the canvas)
> Examples

Here are some examples of radial gradients produced using multiple color stops:

/* A gradient with three color stops equally spaced */
-fx-background-color: radial-gradient(center 50% 50%, radius 50%, red, blue, #16222A);
/* A radial gradient with three color stops, specifying the position of the middle stop in percent */
-fx-background-color: radial-gradient(center 50% 50%, radius 50%, red, blue 85%, #16222A);

4. Repeating Gradients

Unlike in standard web CSS, in which the radial-gradient and repeating-radial-gradient are separate functions, in JavaFX they are combined into a single function.

To create a repeating radial gradient, developers should use keywords repeat or reflect in-between the radius parameter and the color stops.

-fx-background-color: radial-gradient(radius <size>, [repeat| reflect]?; red, blue);

Important: To achieve either a repeating or reflecting effect, the gradient bounds should not expand to fill the container.

The reflecting or repeating portions of the gradient will be applied when the distance between the pixel and the gradient center is greater than the radius.

> Repeating

A repeating gradient will create a gradient from the positional arguments provided, and cycle through the defined color stops until the entire container is covered.

-fx-background-color: radial-gradient(center 50% 50%, radius 20%, repeat, red, red 50%, blue 50%, blue 95%, #00FA9A 95%, #00FA9A 100%);
Repeating Gradient
> Reflecting

A repeating gradient will create a gradient from the positional arguments provided, and reflect it in alternating pattern it so that in each odd cycle the gradient will run in reverse. Again, this is created over the entirety of the defined area.

-fx-background-color: radial-gradient(center 50% 50%, radius 20%, reflect, red, red 50%, blue 50%, blue 95%, #00FA9A 95%, #00FA9A 100%);
Reflecting Gradient

5. Focus Angle and Distance

The focus-angle and focus-distance parameters can be used to move the position of the gradient center without effecting the outer shape of the gradient. They are defined together here, because they represent the radial and polar coordinates of the color-center of the gradient relative to the geometric center. By default both parameters are zero,

For clarity, a stepped gradient is used in each of the below examples. Color stops are defined up to each color change to create a clear contour effect, rather than a pure gradient

> Defining only the focus distance

The focus distance shifts the color center of the gradient towards the outer edge of the gradient shape. The focus distance is expressed as a <percentage> of the radius.

The focus distance of a radial gradient represents a proportional shift of the color center towards the outer edge of the gradient
/* Radial gradient with color center shifted to the right by 100% of the radius (it is therefore on the edge of the outer shape) */
-fx-background-color: radial-gradient(focus-distance 60%, center 50% 60%, radius 35%, red, red 10%, green 10%, green 50%, blue 50%, blue 99%, white 100%);
radial gradient with focus distance defined, but no focus angle

Worth noting that with no focus angle defined, the color center is shifted to the right. Defining a focus angle will rotate the focus center clockwise by the defined amount

> Defining focus distance and angle

The focus angle must be defined alongside the focus-distance parameter, and represents the polar angle between the geometric center of the gradient and the color center using polar coordinates. It should be defined using the <angle> data type

The focus angle represents the polar angle between the geometric center of the gradient and the color center using polar coordinates.
/* Radial gradient with color center moved 50% of the distance towards the outer radius and 90 degrees clockwise*/
-fx-background-color: radial-gradient(focus-angle 125deg, focus-distance 60%,, center 50% 60%, radius 35%, red, red 10%, green 10%, green 50%, blue 50%, blue 99%, white 100%);
radial gradient with focus distance and angle defined

Syntax

/*  Simple elliptical gradient (gradient proportional to container)*/
radial-gradient(radius 50%, red, blue);

/*  Simple circular gradient (gradient size absolute)  */
radial-gradient(radius 50%, red, blue);

/*  Linear gradient with gradient center described using  notation */
radial-gradient(center 50% 50%, radius 50%, #eeaeca, #59708C);

/* A gradient with three color stops equally spaced */
radial-gradient(center 50% 50%, radius 50%, #eeaeca, #59708C, #16222A);

/*  A complex, stripy gradient  */
radial-gradient(center 50% 50%, radius 10%, reflect, red, red 50%, blue 50%, blue 95%, #00FA9A 95%, #00FA9A 100%);

Values

The JavaFX CSS interpreter isn’t a fully-compliant CSS Interpreter, nor does it support all CSS-values you might expect for the related CSS property.

radial-gradient() can have the following values:

ValueDescription
radiusThe overall size of the gradient as it radiates out. The final color stop is applied outside the radius if no gradient cycling is applied.
<color-stop>A <color> and optionally a position defining one color along the gradient
focus-angleAn optional parameter representing the polar coordinate of the color center of the gradient relative to the geometric center
focus-distanceAn optional parameter representing the distance between the color center of the gradient relative to the geometric center
centerThe geometric center of the gradient, specified as a <size>.
[reflect | repeat]An optional parameter defining the behaviour of the gradient when the distance between the pixel being rendered and the geometric center of the gradient is greater than the radius.

See Also