Usage

Registering

The plugin does not automatically register. Register it either for all charts, or for a single chart instance.

All charts

Chart.register(gradient)

Single chart

const chart = new Chart(ctx, {
  // ...
  plugins: [gradient]
});

Configuration

Gradient colors are configured under a gradient key, with one entry per dataset color option that should become a gradient: backgroundColor, borderColor, hoverBackgroundColor, hoverBorderColor, pointBackgroundColor, pointBorderColor, pointHoverBackgroundColor, pointHoverBorderColor, or any other color option the dataset accepts. Each entry selects the scale the gradient follows, and a map of scale values to colors.

Option	Description
axis	Axis (scale) the gradient follows: x, y, or r.
colors	Map of scale value to color, sorted and used as the gradient’s color stops.

const chart = new Chart(ctx, {
  data: {
    datasets: [{
      // data
      gradient: {
        backgroundColor: {
          axis: 'y',
          colors: {
            0: 'red',
            50: 'yellow',
            100: 'green'
          }
        },
        borderColor: {
          axis: 'x',
          colors: {
            0: 'black',
            1: 'white',
            2: 'black',
            3: 'white'
          }
        }
      }
    }]
  }
});

Where to configure

gradient is an ordinary Chart.js dataset option, so besides the dataset itself it can be set anywhere Chart.js resolves dataset options from, in this precedence order (first one that defines a given key wins for that key):

Level	Applies to
dataset.gradient	That dataset only.
options.datasets.<type>.gradient	Every dataset of that chart type, e.g. options.datasets.line.gradient.
options.gradient	Every dataset on the chart.
Chart.defaults.datasets.<type>.gradient	Every dataset of that type, on every chart.
Chart.defaults.gradient	Every dataset, on every chart.

The precedence applies per key, not to the whole gradient object: a chart-level backgroundColor and a dataset-level borderColor both apply to the same dataset. A dataset can opt out of a gradient configured at a less specific level by setting that key to false (or null):

const chart = new Chart(ctx, {
  data: {
    datasets: [
      {
        // Uses the chart-level backgroundColor gradient below, plus its own borderColor gradient.
        gradient: {
          borderColor: { axis: 'y', colors: { 0: 'blue', 100: 'purple' } }
        }
      },
      {
        // Opts out of the chart-level backgroundColor gradient, keeps its own plain color.
        backgroundColor: 'silver',
        gradient: { backgroundColor: false }
      }
    ]
  },
  options: {
    gradient: {
      backgroundColor: { axis: 'y', colors: { 0: 'red', 100: 'green' } }
    }
  }
});

// Every line dataset, on this chart only.
const chart = new Chart(ctx, {
  // ...
  options: {
    datasets: {
      line: {
        gradient: {
          borderColor: { axis: 'y', colors: { 0: 'red', 100: 'green' } }
        }
      }
    }
  }
});

// Every dataset, on every chart.
Chart.defaults.gradient = {
  backgroundColor: { axis: 'y', colors: { 0: 'red', 100: 'green' } }
};

// Every line dataset, on every chart.
Chart.defaults.datasets.line.gradient = {
  borderColor: { axis: 'y', colors: { 0: 'red', 100: 'green' } }
};

See the editable chart options and dataset type samples for the two chart-scoped levels.

Hover and point colors

Chart.js derives each hover color from its own base color: hoverBackgroundColor from backgroundColor and hoverBorderColor from borderColor, and a gradient is passed through unchanged. So a backgroundColor gradient already shows on hover, and so does a borderColor gradient on the hovered border. What does not happen is crossing over: a hovered point’s fill is derived from the dataset’s backgroundColor, never from borderColor. A line dataset with only a borderColor gradient therefore hovers its points with a fill derived from whatever backgroundColor resolves to, which is Chart.js’s default rgba(0, 0, 0, 0.1) when the dataset sets none. Give the dataset a hoverBackgroundColor gradient (or pointHoverBackgroundColor, for line/radar/scatter points) to make the fill follow the same gradient:

const chart = new Chart(ctx, {
  data: {
    datasets: [{
      // data
      gradient: {
        borderColor: {
          axis: 'y',
          colors: {
            0: 'red',
            50: 'yellow',
            100: 'green'
          }
        },
        hoverBackgroundColor: {
          axis: 'y',
          colors: {
            0: 'red',
            50: 'yellow',
            100: 'green'
          }
        }
      }
    }]
  }
});

See the editable background, border, both, hover, and points samples.