Percent Bar

Summary

The Percent Bar Style renders a coloured bar in each cell in a numeric column
The width of the bar is calculated as a percentage of the cell value relative to a provided Min and Max
Min and Max can be set for whole Column or in Ranges, and be hard-coded or based on another Column values
Bars can grow from the left edge, from 0, from a custom baseline, or as a centred axis for negative values
The actual Cell Value (and Percent Value) can also be displayed, above, below or merged with the Bar
An optional Tooltip can show the Cell Value, the Percent Value, or both on hover
By default the bar renders on data rows only but can also display on Group, Summary and Total rows

The Percent Bar Style enables numeric columns to display a coloured bar in each cell.

Each cell bar's width is calculated as a percentage of the cell's value compared to a maximum value.

Anatomy

A Percent Bar cell is composed of three main elements:

Bar — a horizontal coloured bar whose width represents the cell value relative to [Min, Max]
Note
- The bar can grow from the left edge, from 0, from Min, or from a fixed numeric Origin
- It can also use a centred-axis where positive values extend right and negative values extend left
Cell Text (optional) — the cell value and / or the percentage value
Hint
- They can be placed above, below or merged with Bar and on left, right or center of cell (9 possibilities)
- If both are in same spot, they are concatenated with a space (Cell Value first, then Percent Value)
Back Color (optional) — fills the part of the cell that isn't covered by the bar

Ranges

The bar colour is driven by a Cell Range (one colour per range).

A CellRange is used to define a set of cells, and contains 3 properties:

a minimum value
a maximum value
an associated colour

When the cell value falls inside the range, the bar displays the appropriate colour.

Hint

This is useful when wanting a traffic light effect - e.g. 0-30: Red; 31-70: Orange; 71-100: Green

There are 3 types of Ranges which can be provided in a Percent Bar:

Numeric - Range contains all Column cells which fall between the top and bottom values
Percentage - Range contains all Column cells whose value falls in that percentage of all values
Column Comparison - a single colour comparing against another column

Note

There is no limit on how many ranges can be created
But all Ranges must be of the same type (numeric or percentage) - you cannot mix and match

Numeric Range

In a Numeric Range the top and bottom values are numeric values which can be provided in 2 ways:

Hardcoded Values - the user provides the actual numeric values for the range
Dynamic Values - the user selects Col-Min or Col-Max; AdapTable will then automatically evaluate the Column's Minimum or Maximum values and use those

Note

Col-Min or Col-Max values are re-evaluated in real time in response to data changes
For instance, if a cell ticks and now becomes the Column's highest value, all the cells will re-render
Dynamic endpoints are computed across the column's visible rows (so they respect Filters)

Caution

The Styled Column Wizard only permits the automatic Min in the first Range and automatic Max in the last Range

The state shape additionally allows Col-Avg and Col-Median as DynamicRangeEndpoint values.

Hint

For example you can pin a band to "everything above the column average"
These can only be set via Initial State or the API — the wizard exposes Col-Min / Col-Max only

Percent Bar: Numeric Ranges

Fork Fork

Two columns each use a Number Range only (RangeValueType: 'Number'):
- GitHub Stars — three bands with hard-coded thresholds (red / orange / green)
- Closed PRs — one band from Col-Min to Col-Max (purple)

Percentage Range

A Percentage Range has the same shape as a Numeric Range, but each band's Min and Max are expressed as percentages (0–100) along the column's overall value span.

For example, you can create 2 Ranges to render:

the top 50% of cell values in the column in one colour
the bottom 50% of cell values in another

Caution

The percentage is calculated from each cell value relative to the column's value range (Col-Min → Col-Max)
It is not calculated using the number of cells in the column - that is not part of the evaluation

Percent Bar: Percentage Ranges

Fork Fork

Three columns each use a Percentage Range only (RangeValueType: 'Percentage'):
- GitHub Stars — three bands: 0–33, 33–66, 66–100 (red / orange / green); sorted descending — most rows sit in the lowest band, so many bars look red (this is value-based, not row count)
- Closed PRs — two bands: 0–20 and 20–100 (brown / blue)
- GitHub Watchers — two bands: 0–50 and 50–100 (teal / green)

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Percent Bar Percentage Ranges',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'closed_pr_count',
            'github_watchers',
            'language',
            'open_issues_count',
            'closed_issues_count',
            'week_issue_change',
            'has_projects',
            'has_pages',
            'updated_at',
            'pushed_at',
          ],
          ColumnSorts: [
            {
              ColumnId: 'github_stars',
              SortOrder: 'Desc',
            },
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'github_stars',
          Name: 'GitHub Stars three bands',
          PercentBarStyle: {
            RangeValueType: 'Percentage',
            CellRanges: [
              {
                Min: 0,
                Max: 33,
                Color: 'IndianRed',
              },
              {
                Min: 33,
                Max: 66,
                Color: 'DarkOrange',
              },
              {
                Min: 66,
                Max: 100,
                Color: 'ForestGreen',
              },
            ],
          },
        },
        {
          ColumnId: 'closed_pr_count',
          Name: 'Closed PRs bottom 20%',
          PercentBarStyle: {
            RangeValueType: 'Percentage',
            CellRanges: [
              {
                Min: 0,
                Max: 20,
                Color: 'SaddleBrown',
              },
              {
                Min: 20,
                Max: 100,
                Color: 'SteelBlue',
              },
            ],
          },
        },
        {
          ColumnId: 'github_watchers',
          Name: 'GitHub Watchers two bands',
          PercentBarStyle: {
            RangeValueType: 'Percentage',
            CellRanges: [
              {
                Min: 0,
                Max: 50,
                Color: 'CadetBlue',
              },
              {
                Min: 50,
                Max: 100,
                Color: 'MediumSeaGreen',
              },
            ],
          },
        },
      ],
    },
  },
};

Column Comparison

Alternatively, the Percent Bar Style can render by comparing each Cell Value against another column in the row.

Percent Bar: Column Comparisons

Fork Fork

Open Issues uses Column Comparison against Closed Issues (bar width = open issues as a share of closed on that row)
Cell text shows the value and percentage, merged on the bar
Row data for the first few rows is adjusted so you can see under-fill, over-fill, and match cases side by side

Negative Values

By default Percent Bars grow from the left edge of the cell.

For columns whose values can go negative this can sometimes be unhelpful (for example, both +50 and -50 end up rendered as a small bar on the left).

Accordingly, AdapTable provides an Origin property, which controls where the bar grows from.

This property supports 4 available values:

`Origin`	How Bar Grows
`'Auto'` (default)	From left edge unless any cell value or `CellRanges` endpoint is negative, in which case it grows from `0` (centred axis: positive values extend right, negative values extend left)
`'Zero'`	Always from `0`, even when all values are positive
`'Min'`	Always from the left edge (the legacy pre-Origin behaviour)
a number	From that fixed origin (e.g. `Origin: 100` for "deviation from baseline of 100")

PercentBarStyle: {
  Origin: 'Auto',
  CellRanges: [
    { Min: -200, Max: 0, Color: 'rgba(220, 53, 69, 0.55)' },
    { Min: 0, Max: 200, Color: 'rgba(40, 167, 69, 0.55)' },
  ],
}

For variance columns (e.g. "actual vs forecast", "year-on-year change", "P&L vs flat" etc.), 'Auto' provides a centred-axis Percent Bar for free.

Hint

Combine Auto with two CellRanges (one for negatives, one for positives) to get a red/green diverging visual

Percent Bar: Negative Values

Fork Fork

Issue Change uses Origin: 'Auto' (default) with two Number ranges: Col-Min…0 (red) and 0…Col-Max (green)
Positive values extend right from 0; negative values extend left — so +50 and -50 are visually distinct
Cell Value is merged on the bar with Horizontal: 'Center', Vertical: 'Merged'; tooltips show value and percentage
Sorted ascending on Issue Change to scan the diverging bars easily

Custom Numeric Values

Origin can also be set to a fixed number.

When this happens, the bar renders as a "deviation from baseline" visual, where cells above the baseline grow right and cells below it grow left.

PercentBarStyle: {
  Origin: 100,
  CellRanges: [
    { Min: 50, Max: 100, Color: 'rgba(220, 53, 69, 0.55)' },
    { Min: 100, Max: 150, Color: 'rgba(40, 167, 69, 0.55)' },
  ],
}

Hint

A custom numeric Origin is useful for benchmark or target columns
Here the concern is the gap above or below a known reference value (e.g. a price vs par at 100)

Percent Bar: Custom Origin

Fork Fork

Open PRs uses Origin: 100 with two ranges: below 100 (red, bar grows left) and above 100 (green, bar grows right)
Sorted ascending on Open PRs — compare rows under vs over the baseline of 100 open PRs
Cell text shows value and percentage below the bar

Decorating Percent Bars

A few additional properties can be added to a Percent Bar to provide the fully required visual effect.

Back Colour

A Back Colour can be added to the cell containing the Percent Bar.

This will display in the remainder of the cell which is not rendered with the Percent Bar.

Caution

This takes precedence over any BackColour which has been added to the Cell's Style in Column Formatting

Cell Text

The Percent Bar can be configured to additionally display (either or both of) 2 values:

the underlying (but formatted) cell value
the percent value (the cell value as a 0–100% reading along the bar's [Min, Max] scale)

The CellTextProperties object configures the position for both CellValue and PercentValue:

Axis	Options
`Horizontal`	`'Left'` (default), `'Center'` or `'Right'`
`Vertical`	`'Above'`, `'Below'` (default) or `'Merged'` (drawn on top of the bar)

Note

This provides 9 possibilities for both CellValue and PercentValue
If they are both in the same slot, they are concatenated with single space (Cell Value first, then Percent Value)

Hint

For example, you can put cell value below-left and percentage below-right of the same bar (see demo below)
Leave CellTextProperties unset to render the bar with no overlay text

The cell text inherits any matching Column Formatting font (e.g. colour) unless overridden by the optional Font slice on the Percent Bar itself.

The Percent Bar can be provided with a Tooltip which shows the cell value when hovering over it.

The Tooltip can display the actual value in the cell, or its value as a percentage, or both.

Font

The text overlay on a Percent Bar can be styled independently of the rest of the column via the Font property.

Font is a CellFontStyle slice that accepts the standard text properties:

ForeColor — text colour
FontWeight — Normal or Bold
FontStyle — Normal or Italic
FontSize — e.g. Small, Medium, Large
FontFamily — any CSS font family

Note

Font only applies when CellTextProperties is set; it has no effect on the bar itself
When Font is set, AdapTable strips any matching Format Column font properties for that column
Horizontal alignment of the overlay text is driven by CellTextLayout (Horizontal per token)

Percent Bar: Cell Properties

Fork Fork

Five columns illustrate decoration options (all use Number ranges unless noted):
- GitHub Stars — track Back Colour (grey)
- Closed PRs — Tooltip with cell value and percentage on hover
- Open Issues — Cell Value below-left and Percent Value below-right of the bar (two tokens, same Vertical slot but different Horizontal)
- Open PRs — Cell Value merged center on the bar; inherits Column Formatting Style (white)
- GitHub Watchers — Cell Value above-left of the bar

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Percent Bar Properties',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'language',
            'closed_pr_count',
            'has_pages',
            'open_issues_count',
            'open_pr_count',
            'week_issue_change',
            'github_watchers',
            'has_projects',
            'updated_at',
            'pushed_at',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'github_stars',
          Name: 'github_stars Percent Bar',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellRanges: [
              {
                Min: 0,
                Max: 10000,
                Color: 'red',
              },
              {
                Min: 10000,
                Max: 100000,
                Color: 'orange',
              },
              {
                Min: 100000,
                Max: 191435,
                Color: 'green',
              },
            ],
            BackColor: '#d3d3d3',
          },
        },
        {
          ColumnId: 'open_issues_count',
          Name: 'open_issues_count Percent Bar',
          PercentBarStyle: {
            CellRanges: [
              {
                Min: 5,
                Max: 1889,
                Color: 'purple',
              },
            ],
            CellTextProperties: {
              CellTextLayout: {
                CellValue: { Horizontal: 'Left', Vertical: 'Below' },
                PercentValue: { Horizontal: 'Right', Vertical: 'Below' },
              },
            },
          },
        },
        {
          ColumnId: 'closed_pr_count',
          Name: 'closed_pr_count Percent Bar',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 'Col-Max',
                Color: 'blue',
              },
            ],
            ToolTipText: ['CellValue', 'PercentageValue'],
          },
        },
        {
          ColumnId: 'open_pr_count',
          Name: 'open_pr_count Percent Bar',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellTextProperties: {
              CellTextLayout: {
                CellValue: { Horizontal: 'Center', Vertical: 'Merged' },
              },
            },
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 'Col-Max',
                Color: 'Brown',
              },
            ],
            BackColor: '#808080',
          },
        },
        {
          ColumnId: 'github_watchers',
          Name: 'github_watchers Percent Bar',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellTextProperties: {
              CellTextLayout: {
                CellValue: { Horizontal: 'Left', Vertical: 'Above' },
              },
            },
            CellRanges: [
              {
                Min: 0,
                Max: 'Col-Max',
                Color: '#dc143c',
              },
            ],
          },
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-open_pr_count',
          Scope: {
            ColumnIds: ['open_pr_count'],
          },
          Style: {
            ForeColor: 'White',
            Alignment: 'Right',
          },
        },
      ],
    },
  },
};

Defining Percent Bars

Percent Bar Styles can be created at design-time using Styled Column Initial State.

Developer Guide

Providing a Percent Bar Style in Styled Column State

const initialState: InitialState = {
  StyledColumn: {
    StyledColumns: [
      {
        ColumnId: 'github_stars',
        Name: 'Github Stars Bar',
        PercentBarStyle: {
          RangeValueType: 'Number',
          CellRanges: [
            {
              Min: 'Col-Min',
              Max: 10000,
              Color: 'red',
            },
            {
              Min: 10000,
              Max: 100000,
              Color: 'orange',
            },
            {
              Min: 100000,
              Max: 'Col-Max',
              Color: 'green',
            },
          ],
          BackColor: '#d3d3d3',
          CellTextProperties: {
            CellTextLayout: {
              CellValue: { Horizontal: 'Left', Vertical: 'Merged' },
              PercentValue: { Horizontal: 'Right', Vertical: 'Merged' },
            },
          },
          ToolTipText: ['CellValue', 'PercentageValue'],
        },
      },
      {
        ColumnId: 'open_issues_count',
        Name: 'Open Issues Bar',
        PercentBarStyle: {
          ColumnComparison: {
            MinValue: 0,
            MaxValue: 'closed_issues_count',
            Color: 'Brown',
          },
        },
      },
      {
        ColumnId: 'market_share',
        Name: 'Market Share Bar',
        PercentBarStyle: {
          RangeValueType: 'Percentage',
          CellRanges: [
            { Min: 0, Max: 33, Color: '#aed581' },
            { Min: 33, Max: 66, Color: '#7cb342' },
            { Min: 66, Max: 100, Color: '#33691e' },
          ],
          BackColor: '#eceff1',
          CellTextProperties: {
            CellTextLayout: {
              PercentValue: { Horizontal: 'Center', Vertical: 'Above' },
            },
          },
          ToolTipText: ['CellValue'],
          Font: {
            ForeColor: '#0d47a1',
            FontWeight: 'Bold',
            FontSize: 'Small',
          },
        },
      },
    ],
  },
};

Provide ColumnId and add the Style

Supply 3 properties:

ColumnId of Styled Column showing Percent Bar
Name of Styled Column - should be descriptive
A PercentBarStyle object

Either: Create a Number Range

A Number Range (RangeValueType of 'Number') has 3 properties:

Min — lower end of the band (can be a number or 'Col-Min')
Max — upper end of the band (can be a number, 'Col-Max')
Color — bar colour for values that fall in that band (a Colour string)

Note

Col-Min and Col-Max can only appear at the ends of the range group

Or: Create a Percent Range

A Percent Range (RangeValueType of 'Percentage') also has 3 properties, but the axis is 0–100% and each band’s Min / Max are percentages.

Min — lower end of the band (can be a number, or a percentage)
Max — upper end of the band (can be a number or a percentage)
Color — bar colour for values that fall in that band (a Colour string)

(Optional) Set Origin

Origin controls where the bar grows from ('Auto' default, 'Zero', 'Min', or a fixed number). Use 'Auto' or 'Zero' with negative/positive CellRanges for a centred diverging bar; use a numeric origin for a benchmark baseline.

Or: Define a Column Comparison

For column comparison mode, supply ColumnComparison instead of CellRanges:

MinValue — lower end of the scale (often 0)
MaxValue — upper end; usually another column id so the bar compares this cell to that column’s value
Color — bar colour when a cell colour is resolved for the bar

Supply a Back Color

This colour fills the part of the cell not covered by the coloured bar (track / background).

Cell Text and Tooltip

You can control what appears in the cell and tooltip:

CellTextProperties.CellTextLayout — per-token placement of the bar overlay. Set CellValue and/or PercentValue, each as a { Horizontal, Vertical } object:
- Horizontal: 'Left' (default), 'Center' or 'Right'
- Vertical: 'Above', 'Below' (default), or 'Merged' (drawn over the bar)
ToolTipText — lists the tokens to show on hover ('CellValue', 'PercentageValue', both, or neither — see CellTextOptions)

Note

A token only renders when its key is present in CellTextLayout; omit either to hide it. When both land on the same slot they concatenate with a single space (Cell Value first, then Percent Value).

Font

Font (optional) is a text-style slice (CellFontStyle: e.g. ForeColor, FontWeight, FontSize) applied to the CellTextProperties overlay; see Adaptable Style Object.

Note

Horizontal alignment of the overlay text is controlled by CellTextLayout (per-token Horizontal); Font.Alignment is not consulted for the overlay.

Creating Percent Bars

Percent Bar Styles can be created at run-time using the Styled Column UI Wizard.

UI Step by Step Guide

Creating a Percent Bar Style using the Styled Column Wizard

The Wizard guides you through the following steps:

Settings: Name the Column and pick the Type

In the Settings step:

Enter a Name for the Styled Column (must be unique within the Grid)
Pick Percent Bar from the list of Styled Column Types

Scope: Choose the Column and the Rows

The Scope step is shared by every Styled Column. Use it to:

Pick the Column to apply the Percent Bar to — only numeric columns (without an existing Styled Column) are listed.
Choose which row kinds the Percent Bar renders on: Data, Group, Summary and Total.

Note

Percent Bar renders on Data rows by default. Toggle the others on if you also want the bar to appear on aggregated cells in Grouped / Summary / Total rows (aggregated values often make no sense as a percentage, so these are off by default).

Ranges: pick one of three flavours

The Ranges step is where the Percent Bar scale is configured. It exposes three mutually-exclusive tabs — switching tab discards anything configured in the previous tab:

Number Range (default) — any number of value-bounded ranges with hard-coded numeric Min / Max thresholds, each with its own colour. Use this for traffic-light style banding or arbitrary thresholds.
- Each Range has a Min, a Max and a Color (for which transparency can also be set)
- Min and Max can be a hard-coded number or a DynamicRangeEndpoint (Col-Min, Col-Max)
- Click Add New Range to add more
Percentage Range — same shape as Number Range but Min and Max are expressed as 0–100 along the column's overall span. The first band always starts at 0, the last always ends at 100.
Column Comparison — render each cell relative to another column on the same row.
- Supply a Min Value and a Max Value — each can be a number or another column id (picked from a dropdown)
- Supply a single Color

Caution

You cannot mix and match Ranges; they need to be all Number or all Percentage based
Col-Min and Col-Max can only appear at the very start / end of a Number Range set

Hint

There is no limit on the number of Ranges which can be created

Style: Bar Position, Cell Text, Cell Style

The Style step configures how the Percent Bar renders. It is divided into three card sections:

Bar Position — sets the bar's Origin, i.e. where the bar grows from:
- Auto — anchors to the left edge, but centres at 0 when the scale has negatives
- Zero — centres at 0; positives extend right, negatives extend left
- Min — always anchored at the column's minimum (left edge)
Cell Text — choose whether and how to display text on the bar (font properties take precedence over Format Column):
- Cell Value and Percent Value — each token has its own Horizontal (Left / Center / Right) and Vertical (Above / Below / Merged) placement so they can be positioned independently
- Font — optional font properties (colour, weight, italic, size, family) applied to the bar text overlay
Cell Style — extra cell-level decoration around the bar:
- Tooltip Display — show the Cell Value, the Percent Value, both, or neither on hover
- Back Colour — fills the part of the cell not covered by the bar; takes precedence over any background set in Format Column

Note

Two further wizard steps — Tags (when the workspace has tags enabled) and Summary (a read-only review of every previous step) — are shared by all AdapTable modules and not specific to Percent Bars.

FAQ

Can we see the underlying value in a Percent Bar Style cell? Yes — set CellTextProperties.CellTextLayout.CellValue to a { Horizontal, Vertical } placement (and/or PercentValue for the percent reading), either at Design Time or at Run Time.

Can we right align the cell value in a Percent Bar Style cell? Yes — set Horizontal: 'Right' on the token's placement (e.g. CellValue: { Horizontal: 'Right', Vertical: 'Merged' }). Each token is placed independently, so you can have the cell value right-aligned and the percent value left-aligned within the same bar.

Can I show negative and positive values in opposite colours? Yes — leave Origin as 'Auto' (or set it to 'Zero') and supply two CellRanges, one with a negative Min/Max and one with a positive Min/Max. The bar will then render as a centred-axis diverging visual.

Can I make the bar grow from a custom baseline rather than 0 or Min? Yes — set Origin to a number (e.g. Origin: 100). Cells above the baseline grow right and cells below it grow left. Useful for benchmark / target columns.

Can I customise the font of the bar text? Yes — set the Font slice on the PercentBarStyle (ForeColor, FontWeight, FontStyle, FontSize, FontFamily). It takes precedence over the font on any matching Format Column.

Can I show a Percent Bar on Group / Summary / Total rows? Yes — toggle the row kinds you want in the Scope step of the wizard (or set RowScope in Initial State). Percent Bars render on Data rows only by default because aggregated values rarely make sense as a percentage.

Can the Min and Max update automatically as data ticks? Yes — use Col-Min / Col-Max (or Col-Avg / Col-Median via state) as range endpoints. AdapTable re-evaluates these against the column's visible rows in real time and the bars re-render automatically.

Can I make a Percent Bar semi-transparent? Yes — supply an rgba(...) colour string for the Range Color (e.g. 'rgba(40, 167, 69, 0.55)'), or use the colour picker's transparency slider in the wizard.

Can a Percent Bar span multiple columns? No — a Percent Bar applies to a single numeric column. For cross-column comparisons use the ColumnComparison mode, which compares each cell to another column on the same row.

PreviousGradient Style NextBadge Style