Styled Columns in AdapTable

Summary

AdapTable provides 8 Styled Columns which render a column with a rich, data-driven visual style:
- Gradient Style
- Percent Bar
- Badge Style
- Sparkline Column
- Bullet Chart
- Rating Style
- Range Bar
- Icon Style

Styled Columns enable users of AdapTable to visualise their data in sophisticated and powerful ways.

They are designed to enable complicated styles to be defined with just a few clicks (or property settings), while providing a very striking visual effect.

There are 8 Styled Columns provided by AdapTable:

Styled Column	Column Type	Description
Gradient	Numeric	Colours cells by comparing values against one or more ranges
Percent Bar	Numeric	Draws a horizontal bar whose length reflects the value
Badge	Numeric, text	Renders badge(s) in a cell, with optional icons and rules
Sparkline	Numeric array	Renders an AG Grid sparkline in each cell from array data
Bullet Chart	Numeric	Renders a bullet graph inside a cell
Rating	Numeric	Renders a row of icons (e.g. stars) scaled to the cell value
Range Bar	Numeric	Shows value and optional reference on track between min & max
Icon	Any (key lookup)	Maps cell values to icons with presets and optional cell text

Deep Dive

How Styled Columns Work in AdapTable and how to implent them

Each time the application starts up AdapTable retrieves any Styled Column definitions from the StyledColumn section of Initial Adaptable State (or from persisted user state).

For each definition, AdapTable will do 2 things:

Create a Adaptable Column with the properties set based on the definition
Update the existing AG Grid column by attaching a bespoke cell renderer for that style type

Cells re-render when their value changes and when other relevant data changes — for example when a range uses Col-Min / Col-Avg / Col-Max and peer values in the column move.

Design-time and integration checklist

These are the details that most often explain “why doesn't my styled column show?”:

Topic	What to know
`ColumnId`	Must match an AG Grid column id (usually the `field`). A typo or a column not yet in `columnDefs` means the definition is ignored.
One style per column	A column has at most one Styled Column. Each definition sets a single style property (`GradientStyle`, `BadgeStyle`, `SparklineStyle`, etc.) — types are mutually exclusive.
Data type	Numeric styles (`Gradient`, `Percent Bar`, `Bullet Chart`, `Range Bar`, `Rating`) require a numeric column. `Sparkline` needs a `numberArray` column and charts enabled. `Badge` and `Icon` are the most permissive.
Row scope	Each type has default row kinds (data / group / summary / total). Sparklines are data rows only. See Understanding the RowScope object below.
Format Columns	The renderer-owned visuals always come from the Styled Column. Where a style exposes `Font` and/or `Cell` slices (see Adaptable Style Object), those override the matching Format Column properties on the same column; anything left unset still inherits from Format Columns.
Suspended	`IsSuspended: true` keeps the definition but stops rendering — useful for A/B comparison without deleting state.
Runtime check	`adaptableApi.styledColumnApi.getStyledColumnForColumnId(columnId)` returns what AdapTable resolved for that column (or `undefined`).

Find Out More

For Styled Column State and Styled Column API methods see Styled Column Technical Reference

Styled Columns

Fork Fork

This demo contains one example of each of the 8 Styled Columns provided by AdapTable
- Language — Badge Style (each distinct values has its own colour)
- Issue Change — Gradient Style (using a zero-centred gradient)
- GitHub Stars — Percent Bar Style
- History — Sparkline Column (line)
- Open Issues — Bullet Chart Style
- Popularity — Rating Style
- Forks — Range Bar Style
- Trend — Icon Style (trend is a Calculated Column with a CASE expression on Issue Change; uses built-in Trend preset)

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Styled Columns',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn', 'CalculatedColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'StyledColumn',
      Layouts: [
        {
          Name: 'StyledColumn',
          ColumnSorts: [
            {
              ColumnId: 'week_issue_change',
              SortOrder: 'Desc',
            },
          ],
          TableColumns: [
            'name',
            'language',
            'week_issue_change',
            'github_stars',
            'historyLine',
            'open_issues_count',
            'popularityRating',
            'forks_count',
            'trend',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    CalculatedColumn: {
      CalculatedColumns: [
        {
          ColumnId: 'trend',
          FriendlyName: 'Trend',
          Query: {
            ScalarExpression:
              "CASE WHEN [week_issue_change] > 0 THEN 'Up' WHEN [week_issue_change] < 0 THEN 'Down' ELSE 'Flat' END",
          },
          CalculatedColumnSettings: {
            DataType: 'text',
            Resizable: true,
            Width: 120,
          },
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'language',
          Name: 'language Badge',
          BadgeStyle: {
            Badges: [
              {
                Shape: 'Rounded',
                Predicate: {
                  PredicateId: 'Is',
                  Inputs: ['JavaScript'],
                },
                PillStyle: {
                  BackColor: '#f7df1e',
                  ForeColor: '#323330',
                },
              },
              {
                Shape: 'Rounded',
                Predicate: {
                  PredicateId: 'Is',
                  Inputs: ['TypeScript'],
                },
                PillStyle: {
                  BackColor: '#3178c6',
                  ForeColor: 'white',
                },
              },
              {
                Shape: 'Rounded',
                Predicate: {
                  PredicateId: 'Is',
                  Inputs: ['HTML'],
                },
                PillStyle: {
                  BackColor: '#e34c26',
                  ForeColor: 'white',
                },
              },
            ],
          },
        },
        {
          ColumnId: 'week_issue_change',
          Name: 'week_issue_change Gradient',
          GradientStyle: {
            ZeroCentred: {
              NegativeColor: '#ff0000',
              PositiveColor: '#378805',
            },
          },
        },
        {
          ColumnId: 'github_stars',
          Name: 'github_stars PercentBar',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellRanges: [
              {
                Min: 0,
                Max: 10000,
                Color: 'red',
              },
              {
                Min: 10000,
                Max: 100000,
                Color: 'orange',
              },
              {
                Min: 100000,
                Max: 200000,
                Color: 'green',
              },
            ],
            BackColor: '#d3d3d3',
          },
        },
        {
          ColumnId: 'historyLine',
          Name: 'historyLine Sparkline',
          SparklineStyle: {
            options: {
              type: 'line',
              stroke: 'rgb(124, 255, 178)',
              strokeWidth: 2,
              padding: {
                top: 5,
                bottom: 5,
              },
              marker: {
                enabled: true,
                size: 3,
                shape: 'diamond',
              },
            },
          },
        },
        {
          ColumnId: 'open_issues_count',
          Name: 'open_issues_count Bullet',
          BulletChartStyle: {
            RangeValueType: 'Number',
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 'Col-Avg',
                Color: 'rgba(40, 167, 69, 0.35)',
              },
              {
                Min: 'Col-Avg',
                Max: 'Col-Max',
                Color: 'rgba(255, 193, 7, 0.35)',
              },
            ],
            TargetProperties: {
              Target: 'Col-Avg',
              Marker: {
                Shape: 'Line',
                Color: 'var(--ab-color-foreground, #e2e2e2)',
                Size: 2,
              },
            },
            Bar: {Color: '#07c', Height: 8},
          },
        },
        {
          ColumnId: 'popularityRating',
          Name: 'popularityRating Rating',
          RatingStyle: {
            Icon: 'Star',
            Max: 5,
            Size: 16,
            Gap: 2,
            AllowHalf: true,
            ShowValue: true,
            ToolTipText: ['CellValue', 'PercentageValue'],
          },
        },
        {
          ColumnId: 'forks_count',
          Name: 'forks_count RangeBar',
          RangeBarStyle: {
            Min: 0,
            Max: 50000,
            Reference: {
              Value: 'github_watchers',
              Marker: {
                Shape: 'Line',
                Color: 'var(--ab-color-foreground, #e2e2e2)',
                Size: 2,
              },
            },
            Marker: {
              Shape: 'Diamond',
              Color: 'var(--ab-color-accent, #07c)',
              Size: 8,
            },
            Track: {Color: 'rgba(255, 255, 255, 0.35)', Height: 4},
            CellTextProperties: {
              CellTextLayout: {
                CellValue: {Horizontal: 'Left', Vertical: 'Below'},
              },
            },
            OutOfRange: {Mode: 'Overflow', Color: '#ff6b6b'},
          },
        },
        {
          ColumnId: 'trend',
          Name: 'trend Icon',
          IconStyle: {
            Preset: 'Trend',
            CellTextProperties: {
              CellText: ['IconDescription'],
              CellTextPosition: 'After',
            },
            ToolTipText: ['CellValue'],
            Size: 22,
            Gap: 6,
          },
        },
      ],
    },
  },
};

Gradient Style

The Gradient Style will colour numeric cells by comparing their value against a maximum value.

This maximum value can be the highest value in the Column or in a given Range.

Hint

Gradients can be reversed so the colour is lighter (rather than darker) the nearer it is to the max value
You can also provide a Zero-centred gradient for columns that also contain negative numbers

Percent Bar Style

In the Percent Bar Style each cell in the numeric column displays as a relatively sized bar, evaluated using either the cell's actual value or its relative percentage value.

Percent Bar Styles can include multiple Ranges and be styled to show a back colour, Cell Text or a Tooltip.

Badge Style

In the Badge Style each cell in a numeric or text column can be rendered as a Badge.

A Badge can include the Cell Text, or an Icon, or both.

Rules can be provided to determine whether the Badge is displayed.

Hint

This allows you to provide multiple different badge styles for a column depending on the cell value

Sparkline Column

The Sparkline Column style enables columns to be displayed as an AG Grid sparkline.

These are array columns, typically numeric, but objects can also be provided.

Bullet Chart Style

The Bullet Chart Style renders a bullet graph in each cell of a numeric column.

Each cell shows three things in a single row of pixels: the actual value (a bar), a target value (a marker) and optional qualitative bands (e.g. poor / ok / good).

Bullet Charts are particularly useful for KPI columns where each row's value should be compared against a target and classified into a qualitative band.

Hint

Bullet Charts also support Col-Avg and Col-Median as dynamic band/target endpoints
The bands and markers can adapt automatically as the data changes

Rating Style

The Rating Column Style turns a numeric column into a row of repeated icons (such as stars or hearts).

The filled portion reflects the cell value against configurable maximum (with optional half-icon for fractions).

Hint

Use the Rating Style when you want a compact, familiar “score out of five” (or similar) visual

Range Bar Style

The Range Bar Style draws a horizontal track between a minimum and maximum for each numeric cell.

It includes a marker for the cell value and an optional second marker for a reference value.

Optional qualitative bands can tint regions of the track.

It suits KPIs where you need to see “where am I on the scale?” and optionally compare to a benchmark in the same glance.

Icon Column Style

The Icon Column Style maps each cell’s value to a visual (emoji, system icon, or image URL).

Built-in presets (for example flags or status) can be combined with your own key–icon pairs; unmatched values can be hidden or shown as raw text or a fallback icon.

Hint

Icon columns work on any column data type that can be matched as text or a discrete key (not just numeric columns)

Find Out More

See the dedicated help page on each Styled Column to find out more and see relevant demos:

Row Scope

AdapTable allows both run-time and design-time users to decide which Rows will be included in the Style.

This is done using the RowScope property which controls 4 kinds of Rows:

Data — leaf data rows
Group — group rows (when AG Grid Row Grouping is active)
Summary — pinned summary rows
Total — grand-total rows

Note

All Styled Columns can render on all row kinds, with sole exception of Sparkline (which supportes Data rows only)

When RowScope is not explicitly set, AdapTable picks a sensible per-type default:

Styled Column	Default row kinds
Badge	All four — Data, Group, Summary and Total
Sparkline	Data only (the others aren't supported)
All other Styles	Data, Summary and Total (Group excluded)

Note

Only Badge includes Grouped Rows by default because aggregated values rarely make sense for other Styles
AdapTable still allows rendering Styles on Group rows because the Aggregation doesn't have to be sum
For example, it could be min or max, in which case the rendering would fit in with the rest of the column

Deep Dive

Understanding the RowScope object

Shape

RowScope is an object based on Exclude flags.

When a flag is true the row kind is not rendered; missing flags default to include:

RowScope: {
  ExcludeDataRows?: boolean;
  ExcludeGroupRows?: boolean;
  ExcludeSummaryRows?: boolean;
  ExcludeTotalRows?: boolean;
}

For example, to opt a Gradient column into Group rows (overriding the default):

{
  ColumnId: 'closed_pr_count',
  Name: 'Closed PR Gradient',
  GradientStyle: { /* ... */ },
  RowScope: {
    ExcludeGroupRows: false,
  },
}

Caution

Unsupported row kinds (e.g. Group on a Sparkline) are always enforced off
Even if the persisted RowScope explicitly tries to include them, AdapTable strips the flag at load time

Note

The Scope step of the Styled Column Wizard greys out and disables unsupported row kinds
This ensures that they cannot be ticked at run-time

Using Styled Columns

Run-time users are able to add, edit, share, suspend and delete Styled Columns using the Styled Column section in the Settings Panel.

A menu item in the Column Menu opens the Styled Column wizard for the selected column.

Labels follow a consistent pattern:

Create … when no Styled Column exists for that column yet
Edit … when one already does (for example Edit Gradient Column)

Which create actions appear depends on the column’s data type :

Note

Badge and Icon are offered on several types because they do not assume a numeric scale
Numeric-only styles are only listed for numeric columns

Column type	Styles available in Menu
Numeric	`Gradient`, `Percent Bar`, `Bullet Chart`, `Range Bar`, `Rating`, `Badge`, `Icon`
String	`Badge`, `Icon`
String array	`Badge`
Number array	`Badge`, `Sparkline`

Hint

When editing, the wizard opens on a sensible first step for that style
For example Ranges for Gradient or Percent Bar, Mappings for Icon, Style for Range Bar

For full control over ordering and visibility of menu items, see Column Menu Options.

UI Entitlements

The UI Entitlements behaviour for Styled Columns is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that the Styled Columns will still be rendered but Users are not permitted to manage or suspend the Style definitions.

FAQ

Can I apply more than one Styled Column to the same column? No. A column can have at most one Styled Column at a time, and all the types are distinct and mutually exclusive. They all provide different ways to display column data and each has a separate implementation. The wizard reflects this by asking you to pick the Type on the Settings step.

What's the difference between a Badge and an Icon Column? Both can show a small visual in a cell, but they answer different questions:

Badge is rule-driven: each badge is shown when the rule matches the cell (or always, if no Rule is given). A badge is a pill with optional text and an optional icon and you can configure multiple badges per column.
Icon Column is value-mapped: it uses Key → Icon mappings and the renderer looks up the cell's value to find the matching icon. There is exactly one icon per cell, with configurable fallback behaviour for unmatched values.

Hint

Use a Badge when you want rule-based visual labels with optional text
Use an Icon Column when each value should map to a single, fixed glyph (e.g. flag or currency)

Why is a Styled Column (e.g. Percent Bar or Gradient) not shown on grouped or summary rows? Each Styled Column type defines which row kinds (data, group, summary, total) it can render on, and the wizard includes a Scope step to choose columns and those row kinds. Some types are intended only for leaf data rows (for example sparklines). If a style does not appear on an aggregated row, check the Styled Column's Row scope in the wizard or in Adaptable State — not all types apply to every row kind.

How do Styled Columns interact with Format Columns on the same cell? Styled Columns claim specific style slices and override the matching Format Column properties for those slices. In practice that means:

The renderer-owned visuals (gradient tint, percent bar, badge pill, sparkline, bullet chart geometry, rating icons, range track, icon glyph) always come from the Styled Column.
Where a Styled Column exposes a Font and/or Cell slice in its wizard (e.g. Gradient, Percent Bar, Bullet Chart, Rating, Badge, Icon), those properties take precedence over the Format Column for the same column.
Anything the Styled Column leaves unset still inherits normally from any matching Format Column.

Can I temporarily turn a Styled Column off without deleting it? Yes. Every Styled Column can be suspended from the Styled Column section in the Settings Panel. A suspended Styled Column keeps its definition but does not render — useful for quickly comparing styled vs. unstyled, or temporarily disabling a rule.

Why does my Styled Column not appear after I set it in Initial State? The most common reasons are:

The Styled Column's ColumnId doesn't match a column in the grid (typos, or the column hasn't been added yet)
The wrong type is configured for the column's data type (for example a Gradient on a string column)
The Styled Column is suspended or read-only in a way that hides it
For aggregated rows: the Row Scope excludes the row kind you're looking at

Hint

Use getStyledColumnForColumnId in Styled Column API at runtime to check if a Styled Column exists

PreviousTechnical Reference NextGradient Style