The linear-gradient() function is used to create a <linear-gradient> object, which represents a texture consisting of a transition between two or more colors along a straight path.

Default gradient

The simplest linear gradient can be defined using only two colors. The gradient created by default will progress from top to bottom, and the length of the gradient will equal the height of the container.

Default size: Size mimics the size of the container
Default direction: Gradient progresses from top to bottom
Default repeating pattern: None

-fx-background-color: linear-gradient(red, blue);
linear-gradient(red, blue)

Sizing And Directing Gradients

A linear-gradient() function can optionally accept positional parameters to define the dimensions of the gradient to be created. These should be provided before the color stops are specified

linear-gradient(<position>, red, blue);

The optional <position> parameter can be specified in two ways:

  • Direction: "to <side-or-corner>"
  • Direction and Sizing: "from <point> to <point>"

Each of these is described in the following sections.

> Changing gradient direction

Providing a "to <side-or-corner>" instruction such as “to left” or “to bottom right” will set the direction of the gradient, but will not resize it.

Default size: Size mimics the size of the container
Default repeating pattern: None

-fx-background-color: linear-gradient(to right, red, blue);
linear-gradient(to right, red, blue)

Formatting: If specifying a corner, the top/bottom should always come before the left/right, and they should be separated by a space rather than a hyphen. The allowed values for this are:

  • left
  • right
  • top
  • bottom
  • top left
  • top right
  • bottom left
  • bottom right

The gradient in each case will end at the specified location, and start at the opposing corner or side.

> Changing gradient direction and size

Developers requiring more precision in their gradients can specify either a relative or absolute position for the start and end of the gradient by using the "from <point> to <point>" notation.

Defining points

A <point> represents a coordinate in 2-dimensional space and is defined as an x and y coordinate separated by a space.

Points can be defined as either relative or absolute coordinates using <percentage> and <length> data types

Two points should be specified, separated by a space, using the keywords to and from in the following format:

  • Relative coordinates:
    from <percentage> <percentage> to <percentage> <percentage>
  • Absolute coordinates:
    from <length> <length> to <length> <length>

Formatting:

Units: Units must be consistent across all points. Mixing of absolute and relative coordinates is not supported.

-fx-background-color: linear-gradient(from 45% 50% to 65% 50%, red, blue);
linear-gradient(
from 45% 50% to 65% 50%,
red, blue);

Here, the length of the gradient itself is truncated so as to exist only between 45% and 65% on the x-axis. Below 45%, no gradient exists and the color is completely red. Above 65%, it is completely blue.

Percentages represent proportional values relative to the size of the container. Both absolute and relative coordinates can be positive or negative, although only the section of the gradient visible inside the container will be drawn.

Multiple Color Stops

Linear gradients with multiple color stops can be created by specifying extra color stops in a comma-separated list.

Color Stops

<color-stop>

A color-stop’s <color> value, followed by a stop position as either a <percentage> or a <length> along the gradient’s path.

For example:

  • red – A color stop with no position
  • red 50% – A color stop with a position as a percentage
  • #fcc200 30px – Position as a length
  • #fcc200 30 – Position with no units defaults to a length in px

Formatting:

Units: Units must be consistent across all color stops.

Use of lengths: Is percentages are used, then the position of the first and last stops are optional (they will default to 0 and 100% respectively). If lengths are used, the positions of all color stops must be specified.

Examples

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

/* A gradient with three color stops equally spaced */
linear-gradient(to right, red, blue, green);
linear-gradient(to right, red, blue, green);
/* A linear gradient with three color stops, specifying the position of the middle stop in percent */
linear-gradient(to right, red, blue 85%, green);
linear-gradient(to right, red, blue 85%, green);
/* A linear gradient with three color stops, specifying the position of all color stops as lengths*/
linear-gradient(to right, red 15px, blue 65px, green 75px);
linear-gradient(to right, red 15px, blue 65px, green 75px);

Repeating Gradients

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

To create a repeating linear gradient, developers should use keywords repeat or reflect in-between the directional arguments and the color stops.

linear-gradient(<position>, [repeat| reflect]?; red, blue);

Important: To achieve either a repeating or reflecting effect, the gradient bounds should not expand to fill the container, otherwise the repeating pattern will not be visible. Developers will need to accomplish this by setting the size of the gradient to be smaller than the container using from <point> to <point> notation

the linear-gradient() function accepts arguments to size the gradient it paints

The reflecting or repeating portions of the gradient will be applied outside the bounds of the defined gradient. Repeating and reflecting occur at both ends of the gradient (i.e. before the start and after the end). Here, specifying a repeating or reflecting pattern would effect the areas below 25% and above 75% on the x-axis.

1. 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: linear-gradient(from 0% 100% to 7% 85%, repeat, red, red 50%, blue 50%, blue 95%, #00FA9A 95%, #00FA9A 100%);
Repeating Gradient

2. 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: linear-gradient(from 0% 100% to 7% 85%, reflect, red, red 50%, blue 50%, blue 95%, #00FA9A 95%, #00FA9A 100%);
Reflecting Gradient

Syntax

linear-gradient( [[<position> | to <side-or-corner>],]? [[repeat | reflect],]? <color-stop-list> )

/* where <position> = "to <side-or-corner>" or "from <point> to <point>"
*  and <point> = [<percentage> <percentage>] or [<length> <length>]
*  and <color-stop> = [<color> [<percentage> | <length>]?] */

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.

linear-gradient() can have the following values:

ValueDescription
<position>The gradient position as either a “to <side-or-corner>” or “from <point> to <point> statement
[repeat | reflect]The behaviour of the gradient outside of the bounds defined in <position>. If no value is specified, no cycling will be applied.
<color-stop>A color and optionally a position as a <length> or <percentage>

Example

the linear-gradient() function accepts arguments to size the gradient it paints

CSS:

.root{
    -fx-background-color: linear-gradient(to bottom right, #9cecfb, #65c7f7, #0052d4);
}

.content{
    -fx-font-size: 1.4em;
    -fx-background-color: linear-gradient(to right, #ffefba, #ffffff);;
}

.label{
    -fx-background-color: #fcc200;
    -fx-font-weight: bold;
}

FXML:

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.geometry.*?>
<?import javafx.scene.control.*?>
<?import javafx.scene.layout.*?>

<VBox alignment="TOP_CENTER" prefHeight="250.0" prefWidth="300" spacing="25.0" stylesheets="@../css/styles.css"
      xmlns="http://javafx.com/javafx/10.0.2-internal">
    <Label alignment="CENTER" maxWidth="300" text="linear-gradient() example" />
   <TextArea styleClass="content" text="Pale gradient defined from left to right on this element. Blue linear gradient defined on root element" wrapText="true" />
    <padding>
        <Insets bottom="10.0" left="10.0" right="10.0" top="10.0" />
    </padding>
</VBox>

See Also