Styled Columns

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 Styles can only be applied on Numeric Columns

Anatomy

A Gradient Style consists of 3 main elements:

  • A background fill applied to the whole cell
  • A colour-based Range interpolated from the cell value's position on the active [Min, Max] scale
  • Optionally an auto-contrast foreground so the value stays readable on darker fills

Note

  • The colour ramp is alpha-driven by default — lighter at the minimum, opaque at the maximum
  • Use MinAlpha / MaxAlpha to clamp that ramp at either end

By default, higher values in the active band look darker (more opaque) and lower values look lighter.

Hint

  • See Reversing Gradients below on how to emphasise lower values within a band
  • Alternatively use Zero Centred Gradients when sign and distance from 0 matter

Ranges

A Gradient Column needs to know two things for every cell:

  1. The [Min, Max] window the cell value sits inside
  2. The base Color to interpolate the alpha ramp over that window

Both come from the Gradient's active Range configuration.

Within the chosen window AdapTable linearly interpolates the alpha — fading from the MinAlpha end (lightest) to the MaxAlpha end (most opaque), so cells naturally darken as their value moves up.

AdapTable provides four mutually-exclusive Range flavours to deal with all possible use cases:

Caution

Only one Range Type can be active on a Gradient at a time — they're not layered

Range TypeDescription
NumberOne or more value bands with literal or column-aggregate boundaries; the everyday choice for traffic-light style banding (e.g. red / amber / green thresholds)
PercentageBands expressed as 0–100 along the column's overall span
Zero CentredA diverging two-band gradient that splits at 0 - designed for signed values (P&L, deltas, changes) where the sign as well as the magnitude matters
Column ComparisonColour each cell relative to another column on the same row - designed for cross-column ratios like "open vs closed issues" or "filled vs target quantity"

Number Range

A Number Range is the default and most flexible Range type.

It is a chain of bands that together cover the values you care about; each band has its own Min, Max, Color.

A Number Range has the following 5 characteristics:

  • The bands are contiguous. AdapTable keeps consecutive bands stitched together — if you change one band's Max, the next band's Min follows automatically (and vice-versa). There are no gaps and no overlaps.
  • There is no upper limit on how many bands you can add. A single band is fine (one colour across the whole range), and you can keep clicking Add New Range to split it further.
  • Min and Max can be hard-coded numbers — useful when you have known thresholds (e.g. 0, 1000, 5000).
  • Min of the first band and Max of the last band can be dynamic — set via Col-Min (first band only) and Col-Max (last band only) so the range stretches to whatever the column's actual extreme values turn out to be.
  • The state shape additionally allows Col-Avg and Col-Median as dynamic Range endpoint values (so you can pin a band to "everything above the column average"), but currently they can only be set via Initial State or API — the wizard exposes Col-Min / Col-Max only.

Note

  • Col-Min, Col-Max, Col-Avg and Col-Median are computed across the column's visible rows
  • They re-evaluate in real time as data ticks or filters change
Gradient Style: Number Ranges
Fork
  • Three columns each use a Number Range only (RangeValueType: 'Number'):
    • Open PRs — one band with hard-coded Min / Max (purple)
    • Closed Issues — three contiguous bands (red / orange / green) with Col-Min and Col-Max on the outer bands
    • Open Issues — one band from Col-Min to Col-Max (blue)

Percentage Range

A Percentage Range has the same shape as a Number Range.

It is also a chain of contiguous bands, each with a Color.

However, the band boundaries are expressed as percentages between 0 and 100, not absolute numbers.

Hint

This lets you describe "bottom 20%" or "top 10%" without knowing the column's actual min/max ahead of time

The first band's Min is always locked to 0 and the last band's Max is always locked to 100.

AdapTable then maps each cell's value onto that 0–100 axis relative to Col-Min and Col-Max and selects the matching band.

Caution

  • The percentage is calculated from the cell value relative to the column's value range (Col-Min → Col-Max)
  • It is not the cell's row-position percentile — the number of cells in the column doesn't enter the calculation
Gradient Style: Percentage Ranges
Fork
  • Three columns each use a Percentage Range only (RangeValueType: 'Percentage'):
    • Closed PRs — two bands: 0–20 (brown) and 20–100 (grey) — highlights the bottom 20% of values in the column
    • GitHub Stars — three bands: 0–25, 25–75, 75–100 (red / orange / green); sorted descending so the ramp is easy to read
    • GitHub Watchers — two bands: 0–50 and 50–100 (blue / green)

Zero Centred Range

For columns that contain both negative and positive values, AdapTable provides a zero-centred diverging gradient option.

Hint

A common use case is showing changes (e.g. price movements, P&L) where magnitude matters as much as the sign

This produces two bands that meet at 0:

  • one between Col-Min and 0
  • one between 0 and Col-Max

Note

  • The negative band is automatically reversed
  • This means that values get darker the further they are from zero in either direction
Gradient Style: Zero Centred
Fork
  • Issue Change uses a Zero Centred gradient (ZeroCentred):
    • negatives in Red — the negative band is automatically reverse-shaded, so values get darker the further below 0 they are
    • positives in Green — darker the higher above 0
    • cells get darker the further they are from zero in either direction
  • Auto Contrast Text is enabled so values stay readable on the darker fills
  • The grid is sorted on Issue Change (ascending) to make the diverging effect easier to see

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
  • Open Issues has a (purple) Gradient Column Style that uses a Column Comparison with Closed Issues (each cell is coloured relative to closed issues on the same row)
  • Hover a cell to see tooltips with the cell value and percentage value along the comparison scale (ToolTipText)

Styling the Gradient

In addition to choosing the type of range there are a number of other options that AdapTable provides to allow you to style the Gradient to match your precise requirements.

Reversed Gradients

Within each band, the default alpha ramp runs from faint at the minimum to opaque at the maximum.

This means that, by default, higher cell values look darker.

AdapTable provides an option to flip that ramp inside that band.

By setting ReverseGradient: true on a band, the low end renders saturated and the high end faint, so lower values draw more attention (e.g. fewer open PRs, lower risk scores, older IDs).

Caution

Only Number and Percentage Ranges can be given a Reverse Gradient (not Zero-Centred or Column Comparison)

Deep Dive

Reverse Gradient vs Zero Centred

Gradient Style: Reverse Gradient
Fork
  • Two columns use the same Col-Min…Col-Max window so you can compare ramp direction:
    • Open PRs — default ramp (higher values are darker)
    • Closed PRs — ReverseGradient: true on the band (lower values are darker)

Alpha Bounds

By default the fill interpolates from fully transparent at the range minimum to fully opaque at the maximum.

You can clamp that ramp with optional MinAlpha and MaxAlpha (each 0–1).

For example to keep the lightest cells slightly tinted (MinAlpha: 0.1) or to cap how strong the darkest cells become (MaxAlpha: 0.85).

Gradient Style: Alpha Bounds
Fork
  • GitHub Stars uses one Col-Min…Col-Max band with MinAlpha: 0.1 and MaxAlpha: 0.85
  • The lowest values stay slightly tinted rather than fully faded; the highest values never reach full opacity
  • Sorted descending on GitHub Stars so the ramp is easy to compare down the column

Auto Text Contrast

AdapTable provides an Auto Text Contrast option.

This sets the cell’s foreground colour from the computed background so values stay readable on dark fills.

It is turned on by setting the AutoContrastText property to true.

Note

This overrides Format Column fore colour for Gradient cells (same idea as readable text on a heat map)

Hint

The Zero Centred demo enables Auto Contrast Text on Issue Change

Tooltips

Gradient columns can expose the same optional tooltip tokens as Percent Bar and Bullet Chart:

  • CellValue - the display value of the current cell
  • PercentageValue - the cell’s position along the active min–max scale for that cell (including column comparison bounds)

Hint

The Column Comparison demo enables both tooltip tokens on Open Issues

Formatting Gradient Columns

A Gradient Column cell can still be styled and formatted by a Format Column on the same column — but the two are merged by slice rather than one wholesale replacing the other.

For each cell AdapTable composes the final look from two style "slices":

  • Cell slice — background colour, border, border radius, padding
  • Font slice — fore colour, weight, italic, size, family, alignment

Precedence is decided per slice:

  • The Cell background is always owned by the Gradient — the gradient tint is the cell fill, so any Format Column BackColor on the same column is ignored.
  • The Font slice is normally inherited from the Format Column. However when GradientStyle.Font is set, those font properties take precedence over the matching Format Column font properties for that column (so a Gradient with its own font can guarantee a consistent typography across the cells it owns).
  • AutoContrastText: true is an additional, per-cell override on top of either of the above — AdapTable picks a readable fore colour from the computed background for that cell, overriding both Format Column fore colour and any GradientStyle.Font.ForeColor for legibility on darker fills.
  • Display Formats, Conditional Styles and alignment that don't conflict with a claimed slice continue to apply as normal (e.g. a numeric formatter from the Format Column still controls how the number is rendered).

Important

  • The short version: the Gradient owns the cell background unconditionally; it can optionally claim Font;
  • AutoContrastText always wins for legibility; everything else inherits from the Format Column

Find Out More

See Styled Columns Overview for the full slice-based precedence model that applies to every Styled Column type.

Gradient Style: Formatting
Fork
  • In this example we provided a Gradient Column Style for GitHub Stars
  • 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

Defining Gradient Columns

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

Developer Guide

Providing a Gradient Style in Styled Column State

const initialState: InitialState = {
  StyledColumn: {
    StyledColumns: [
      {
        Name: 'Closed Issues',
        ColumnId: 'closed_issues_count',
        GradientStyle: {
          RangeValueType: 'Number',
          CellRanges: [
            {
              Min: 'Col-Min',
              Max: 1000,
              Color: 'Red',
            },
            {
              Min: 1000,
              Max: 5000,
              Color: 'Orange',
            },
            {
              Min: 5000,
              Max: 'Col-Max',
              Color: 'Green',
            },
          ],
          MinAlpha: 0.15,
          MaxAlpha: 0.85,
          Font: {
            FontWeight: 'Bold',
            FontStyle: 'Italic',
          },
        },
      },
      {
        Name: 'Closed PRs',
        ColumnId: 'closed_pr_count',
        GradientStyle: {
          RangeValueType: 'Percentage',
          CellRanges: [
            {
              Min: 0,
              Max: 20,
              Color: 'Brown',
            },
            {
              Min: 20,
              Max: 100,
              Color: 'Gray',
            },
          ],
        },
      },
      {
        Name: 'Issue Change',
        ColumnId: 'week_issue_change',
        GradientStyle: {
          ZeroCentred: {
            NegativeColor: '#ff0000',
            PositiveColor: 'LightGreen',
          },
          AutoContrastText: true,
        },
      },
      {
        Name: 'Open vs Closed Issues',
        ColumnId: 'open_issues_count',
        GradientStyle: {
          ColumnComparison: {
            MinValue: 0,
            MaxValue: 'closed_issues_count',
            Color: 'Purple',
          },
          ToolTipText: ['CellValue', 'PercentageValue'],
        },
      },
    ],
  },
};
1
Provide ColumnId, Name and add the Style
  • Supply ColumnId of the Styled Column
  • Give the Style a recognisable, unique Name
  • Add a GradientStyle object
2
Specify the Type of Range (CellRanges only)

When using CellRanges, the RangeValueType property can take 2 values:

  • Number - any number or Col-Min / Col-Max (the default)
  • Percentage - any number from 0-100

Note

ZeroCentred and ColumnComparison are separate, mutually exclusive options — they do not use RangeValueType or CellRanges

3
Either Add Cell Ranges...

Use CellRanges to define one or more value bands, each with its own colour.

Each Range has these properties:

  • Min - lower end (number, percentage, or a DynamicRangeEndpoint like Col-Min / Col-Avg / Col-Median / Col-Max)
  • Max - upper end (same value forms as Min)
  • Color - colour applied within the range
  • ReverseGradient (optional) - when true, reverses the alpha ramp within that band so lower values render darker (see CellColorRange)

Caution

  • Col-Min and Col-Max can only appear at start / end of range set
  • You cannot mix Number and Percentage ranges in the same Gradient
4
...Or Provide a Column Comparison...

Use ColumnComparison to colour each cell based on its value relative to another column on the same row. Supply:

  • MinValue - lower bound (a number or another column id)
  • MaxValue - upper bound (a number or another column id)
  • Color - colour of the gradient
5
...Or Use a Zero-Centred Gradient

For columns that contain both negative and positive values, use ZeroCentred to produce a diverging gradient that splits at 0. Supply:

  • NegativeColor - colour applied to the Col-Min…0 band (reverse-shaded so larger negatives are darker)
  • PositiveColor - colour applied to the 0…Col-Max band

Note

ZeroCentred, CellRanges and ColumnComparison are mutually exclusive

6
(Optional) Tune the Alpha Ramp

By default a cell at the low end of its range renders faintly (MinAlpha: 0.15) and a cell at the high end renders fully opaque (MaxAlpha: 1). Set either property to clamp that ramp:

  • MinAlpha: 0 to fully fade the lowest values out
  • MaxAlpha: 0.85 to cap how strong the darkest cells become
7
(Optional) Enable Auto Contrast Text

AutoContrastText automatically picks a readable foreground colour from the computed background, so values stay legible on dark fills.

8
(Optional) Display a Tooltip

ToolTipText accepts array containing either or both of:

  • 'CellValue' - the formatted cell value
  • 'PercentageValue' - the cell's position along the active min–max scale for that cell (including column-comparison bounds)
9
(Optional) Provide a Font

Font is optional Font Style applied to gradient cell text.

Note

Font takes precedence over Format Columns

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

FAQ

Can I show negative and positive values in opposite colours? Yes — use GradientStyle.ZeroCentred with a NegativeColor and a PositiveColor. AdapTable splits the column at 0, reversing the negative band so values get darker the further they are from zero in either direction.

How do I make lower values darker without using Zero Centred? Set ReverseGradient to *true on the band (or wizard Reverse Gradient checkbox) for a Number or Percentage range.

Can we use a Gradient Style asa Heat Map or spanning multiple columns? No, Gradient Styles dont support Heat Maps or continuous multi-column scales. We plan to introduce a Heat Map Styled Column Type which will contain a user-defined midpoint with automatic min/max ends and for colouring a group of columns with row- vs group-normalized scales and per-row reverse.

PreviousStyled ColumnsNextPercent Bar Style