AdapTable Version:

Framework:

Gradient Column Style

Summary

The Gradient Column Style is used to style all cells in a Column based on a provided Gradient
Each cell is coloured according to its value relative to a provided Min and Max number
These Min and Max numbers can be set for the whole Column or in Ranges
Each set of Min and Max numbers can be hardcoded or based on the values in another Column

The Gradient Style applies dynamic styling to a Numeric Column.

Each cell is coloured according to a gradient value.

This is calculated in relation to a provided minimum and maximum value.

These minimum and maximum values can use either Ranges or a Column Comparison.

Caution

Gradient Columns can only be applied on Format Columns which have a Scope of a single, numeric Column

Ranges

A Range is used to define a set of cells. It has 3 properties:

a minimum value
a maxium value
an associated colour

Each cell in the column is coloured using the cell value against the range's boundaries.

The minimum and maximum values in a Range can themselves be provided in 2 ways:

a hardcoded value
using Col-Min or Col-Max to dynamically determine the Column's Minimum or Maximum values

Note

Col-Min or Col-Max values re-evaluate in real time in response to data changes
- e.g. if a cell ticks and now becomes the Column's highest value, all the cells will re-render

There is no limit on how many ranges can be created.

Percentage Ranges

By default Ranges are Numeric, i.e the Range values are numbers (either hard-coded or dynamically derived). But there is an option to create Ranges where the values are Percentage, rather than Numbers.

Caution

The percentage calculation is based on the cell value as a percentage of all the values in the column
It is not calculated using the number of cells in the column - that is not part of the evaluation

Gradient Style

Fork Fork

This example has 4 Columns provided with a Gradient Column Style:
- Open Prs has a single Range in purple - using hard-coded values
- Closed Issues has 3 Ranges - in Red, Orange and Green respectively
- Open Issues has a single Range in blue - using Col-Min and Col-Max
- Closed Prs has 2 Ranges - in Brown and Gray that use Percentages (1-20, 20-100)

Expand to see the Gradient Style Definitions

StyledColumn: {
  StyledColumns: [
    {
      ColumnId: 'open_pr_count',
      GradientStyle: {
        CellRanges: [
          {
            Min: 0,
            Max: 254,
            Color: '#b042ff',
          },
        ],
      },
    },
    {
      ColumnId: 'open_issues_count',
      GradientStyle: {
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 'Col-Max',
            Color: 'Blue',
          },
        ],
      },
    },
    {
      ColumnId: 'closed_issues_count',
      GradientStyle: {
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 1000,
            Color: 'Red',
          },
          {
            Min: 1000,
            Max: 5000,
            Color: 'Orange',
          },
          {
            Min: 5000,
            Max: 'Col-Max',
            Color: 'Green',
          },
        ],
      },
    },
    {
      ColumnId: 'closed_pr_count',
      GradientStyle: {
        RangeValueType: 'Percentage',
        CellRanges: [
          {
            Min: 0,
            Max: 20,
            Color: 'Brown',
          },
          {
            Min: 20,
            Max: 100,
            Color: 'Gray',
          },
        ],
      },
    },
  ],
},

import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Gradient Styled Column',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'open_pr_count',
            'name',
            'closed_issues_count',
            'language',
            'open_issues_count',
            'has_projects',
            'closed_pr_count',
            'week_issue_change',
            'has_pages',
            'updated_at',
            'pushed_at',
            'github_stars',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'open_pr_count',
          GradientStyle: {
            CellRanges: [
              {
                Min: 0,
                Max: 254,
                Color: '#b042ff',
              },
            ],
          },
        },
        {
          ColumnId: 'open_issues_count',
          GradientStyle: {
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 'Col-Max',
                Color: 'Blue',
              },
            ],
          },
        },

        {
          ColumnId: 'closed_issues_count',
          GradientStyle: {
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 1000,
                Color: 'Red',
              },
              {
                Min: 1000,
                Max: 5000,
                Color: 'Orange',
              },
              {
                Min: 5000,
                Max: 'Col-Max',
                Color: 'Green',
              },
            ],
          },
        },
        {
          ColumnId: 'closed_pr_count',
          GradientStyle: {
            RangeValueType: 'Percentage',
            CellRanges: [
              {
                Min: 0,
                Max: 20,
                Color: 'Brown',
              },
              {
                Min: 20,
                Max: 100,
                Color: 'Gray',
              },
            ],
          },
        },
      ],
    },
  },
};

Reversing the Gradient

By default a Gradient will display higher numbers darker than lower ones. Sometimes, however, the preferred behaviour is for lower numbers in the Range to display darker.

Hint

A common use case is negative numbers where users want the Gradient to be darker the lower the number

Gradient Style: reversed

Fork Fork

This example shows a Column with a Reversed Gradient Style:
Issue Change has 2 ranges:
- one for negative numbers in Red - between Col-Min and 0. It uses a Reverse Gradient so the numbers are darker the lower they are
- one for positive numbers in Green - between 0 and Col-Max
We have sorted on the Column also to display this effect more easily

Expand to see the Gradient Style Definitions

StyledColumn: {
  StyledColumns: [
    {
      ColumnId: 'week_issue_change',
      GradientStyle: {
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 0,
            Color: '#ff0000',
            ReverseGradient: true,
          },
          {
            Min: 1,
            Max: 'Col-Max',
            Color: 'LightGreen',
          },
        ],
      },
    },
  ],
},

Column Comparison

Alternatively, the Gradient Style can render using a Column Comparison. This compares each Cell Value to that of another, defined, column in the row.

Hint

This is useful if you want to colour the Gradient using the cell Value as a % fill of another column's value

Gradient Style: Column Comparison

Fork Fork

The Open Issues Column has been given a (purple) Gradient Column Style that uses a Column Comparison with the Closed Issues column

Expand to see the Gradient Style Definitions

StyledColumn: {
  StyledColumns: [
    {
      ColumnId: 'open_issues_count',
      GradientStyle: {
        ColumnComparison: {
          MinValue: 0,
          MaxValue: 'closed_issues_count',
          Color: 'Purple',
        },
      },
    },
  ],
},

Formatting Gradient Columns

The cell value that is displayed inside a Gradient Column can be formatted like any other cell. Any Styles or Display Formats provided in Column Formatting will be applied to the cell.

Caution

The only exception is the BackColour property which will be ignored since that is derived from the Gradient Column

Gradient Style: Formatting

Fork Fork

In this example we provided a Gradient Column Style for the Github Stars Column
We also styled that Column to be centre-aligned and show a Numeric Display Format
Additionally we provided a Conditional Style so that cells which are greater than 100K display a Fore Color of Gray and Bold

Expand to see the Gradient Style and Format Colummn Definitions

StyledColumn: {
  StyledColumns: [
    {
      ColumnId: 'github_stars',
      GradientStyle: {
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 'Col-Max',
            Color: 'LightGreen',
          },
        ],
      },
    },
  ],
},
FormatColumn: {
  FormatColumns: [
    {
        Name: 'FormatColumn-github_stars-208',
      Scope: {
        ColumnIds: ['github_stars'],
      },
      Style: {
        FontWeight: 'Bold',
        ForeColor: 'Gray',
      },
      Rule: {
        Predicates: [{PredicateId: 'GreaterThan', Inputs: [100000]}],
      },
    },
    {
      Name: 'FormatColumn-github_stars-209',
      Scope: {
        ColumnIds: ['github_stars'],
      },
      DisplayFormat: {
        Formatter: 'NumberFormatter',
        Options: {Multiplier: 0.001, Suffix: 'K'},
      },
      Style: {
        Alignment: 'Center',
      },
    },
  ],
},

import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Gradient Style Column Formatting',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'github_watchers',
            'has_projects',
            'open_pr_count',
            'closed_issues_count',
            'has_pages',
            'open_issues_count',
            'updated_at',
            'week_issue_change',
            'pushed_at',
            'closed_pr_count',
          ],
          ColumnSorts: [
            {
              ColumnId: 'github_stars',
              SortOrder: 'Desc',
            },
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'github_stars',
          GradientStyle: {
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 'Col-Max',
                Color: 'LightGreen',
              },
            ],
          },
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-github_stars',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Style: {
            FontWeight: 'Bold',
            ForeColor: 'Gray',
          },
          Rule: {
            Predicates: [{PredicateId: 'GreaterThan', Inputs: [100000]}],
          },
        },
        {
          Name: 'formatColumn-github_stars',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          DisplayFormat: {
            Formatter: 'NumberFormatter',
            Options: {Multiplier: 0.001, Suffix: 'K'},
          },
          Style: {
            Alignment: 'Center',
          },
        },
      ],
    },
  },
};

Defining Gradient Columns

Gradient Column Styles can be created at design-time via Styled Column Initial Adaptable State.

Creating Gradient Columns

Gradient Column Styles can be created at run-time using the Styled Column UI wizard.

UI Step by Step Guide

Creating a Gradient Column Style using the Styled Column Wizard

There are a few stages when creating a Gradient Column Style:

Select Gradient Column

The 1st step of the Wizard displays the different Styled Column Types available. Select Gradient (the default value)

Select a Column

The 2nd step of the Wizard displays all the numeric columns available in AG Grid (which do not already have a Styled Column). Choose the Column for which you want to set a Style.

Create Gradient Style using Ranges...

The 3rd step of the Wizard is where the Style is created. This will typically include creating one ore more Ranges.

Note

AdapTable creates a default Range for convenince
This is a Number Range using current highest and lowest Column values and a Green colour

Each Range has 3 main properties:

Lower Value
Higher Value
A Colour (for which transparency can also be set)

The Ranges can be one of two types:

Number (the number can be either hard-coded or dynamically evaluated)
Percentage (e.g. top 50%)

Caution

You cannot mix and match Range Types; they need to be all Number or all Percentage based

If using a Number Range, there are 2 options for providing values:

hard-coded values
the Column's dynamically evaluated Min and Max values

Note

By default the Range will show the Gradient based on highest to lowest number
However, there is an option to Reverse the Gradient

If using a Percentage Range, only numeric values (treated as percentages) can be provided.

You can click the Add New Range button to add more Ranges to your collection

Hint

There is no limit on the number of Ranges which can be created
The Wizard only allows automatic Col-Min and Col Max values to be used in the first and last Ranges

.,.or Create Gradient Style using Column Comparison

An alternative to Ranges is to create a Column Comparison by checking the Use a Column Comparison checkbox.

This allows you to specify which other Columns in the Grid to use to calculate the Gradient.

Similar to a Range you need to provide 3 properties:

Min Value
Max Value
A Colour (for which transparency can also be set)

The Min and Max values can be either:

a hard-coded number
the name of a Column selected via the dropdown

FAQ

Can I switch the direction of the Gradient? Yes, set ReverseGradient to true and the cell’s gradient will be darker the lower the cell value

Can we create a Gradient Style that spans multiple columns? Not at the moment - Gradient Style works on a single column only. However we do have an Enhancement Request for a Heat Map style which will include multiple columns, which we hope to introduce in the near future.

PreviousStyled Columns NextPercent Bar Style

Framework: