AdapTable Version:

Framework:

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 percentage of cell value compared to a provided Min and Max value
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 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.

As with the Gradient style, a Percent Bar can use one of 2 objects when evaluating:

one or more Ranges
a Column Comparison

Caution

Percent Bar Styles can only be applied on Styled 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

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 2 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

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, as the name implies, numeric values.

The top and bottom values in the Range 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
- e.g. if a cell ticks and now becomes the Column's highest value, all the cells will re-render
Caution
The Format Column Wizard only permits the automatic Min in the first Range and automatic Max in the last Range

Percent Bar: Numeric Ranges

Fork Fork

This example has 2 Columns provided with a Percent Bar Style that uses Numeric Ranges:
- Github Stars has 3 ranges, rendered in red, amber and green, each using a 'hard-coded' value
- Closed Prs 1 range using 'Col-Min' and 'Col-Max'

Expand to see the Styled Column Definitions

StyledColumn: {
  StyledColumns: [
    {
      ColumnId: 'github_stars',
      PercentBarStyle: {
        RangeValueType: 'Number',
        CellRanges: [
          {
            Min: 0,
            Max: 10000,
            Color: 'red',
          },
          {
            Min: 10000,
            Max: 100000,
            Color: 'orange',
          },
          {
            Min: 100000,
            Max: 191435,
            Color: 'green',
          },
        ],
       },
    },
    {
      ColumnId: 'closed_pr_count',
      PercentBarStyle: {
        RangeValueType: 'Number',
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 'Col-Max',
            Color: 'purple',
          },
        ],
      },
    },
  ],
},

Percentage Range

A Percentage Range allows users to provide ranges where each cell is calculated as a percentage of the whole column.

For example, a user can create 2 ranges - one containing the top 50% of cell values in the column, and the other containing the bottom 50% of cell values.

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

Percent Bar: Percentage Ranges

Fork Fork

In this example the Github Stars Column contains a Percent Bar Style that uses 3 Percentage-based Ranges:
- 0-33% - rendered in red
- 33-66% - rendered in amber
- 66-100% - rendered in green
Note: Because most of the column's cell values are in the lowest range, most are red (i.e. it is not evenly distributed)

Expand to see the Styled Column Definitions

StyledColumn: {
  StyledColumns: [
    {
      ColumnId: 'github_stars',
      PercentBarStyle: {
        RangeValueType: 'Percentage',
        CellRanges: [
          {
            Min: 0,
            Max: 33,
            Color: 'red',
          },
          {
            Min: 33,
            Max: 66,
            Color: 'orange',
          },
          {
            Min: 66,
            Max: 100,
            Color: 'green',
          },
        ],
      },
    },
  ],
},

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

This example has a Percent Bar Style on the Open Issues Column using a Column Comparison against Closed Issues
We amended the usual row data for the first rows to illustrate different use cases more easily

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 each cell in a 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 Value

The Percent Bar can be configured to display the underlying cell value.

This can be the actual Cell Value, or the Cell Value calculated as a percentage, or both.

Note

The Style of the Cell Value will use whatever Column Formatting has been provided for the Column
This includes Alignment, but many other Adaptable Style properties as well (e.g. Colour)

The CellTextPosition property in the Percent Bar Definition allows you configure how the Text is placed relative to the Percent Bar; there are 3 values:

Above
Below (the default)
Merged (the text is placed on top of the Percent Bar)

Tool Tip

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

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

Percent Bar: Cell Properties

Fork Fork

This example has 5 Percent Bars all with extra cell style properties:
- Github Stars has a Back Colour of Gray
- Closed PRs renders a Tool Tip when hovering on the Cell which includes both the Cell Value and its Percentage Value
- Open Issues displays the Cell Value and its Percentage Value below the Percent Bar
- Open PRs displays the Cell Value merged with the Percent Bar, and it uses the Column Formatting Style of white font and right alignment
- Github Watchers displays the Cell Value above the Percent Bar

Expand to see the Styled Column Definitions

StyledColumn: {
  StyledColumns: [
    {
      ColumnId: 'github_stars',
      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',
      PercentBarStyle: {
        CellRanges: [
          {
            Min: 5,
            Max: 1889,
            Color: 'purple',
          },
        ],
        CellText: ['CellValue', 'PercentageValue'],
      },
    },
    {
      ColumnId: 'closed_pr_count',
      PercentBarStyle: {
        RangeValueType: 'Number',
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 'Col-Max',
            Color: 'blue',
          },
        ],
        ToolTipText: ['CellValue', 'PercentageValue'],
      },
    },
    {
      ColumnId: 'open_pr_count',
      PercentBarStyle: {
        RangeValueType: 'Number',
        CellText: ['CellValue'],
        CellTextPosition: 'Merged',
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 'Col-Max',
            Color: 'Brown',
          },
        ],
        BackColor: '#808080',
      },
    },
    {
      ColumnId: 'github_watchers',
      PercentBarStyle: {
        RangeValueType: 'Number',
        CellText: ['CellValue'],
        CellTextPosition: 'Above',
        CellRanges: [
          {
            Min: 'Col-Min',
            Max: 'Col-Max',
            Color: '#dc143c',
          },
        ],

      },
    },
  ],
},

and this is the Column Format on the Open PRs Column:

FormatColumn:{
  FormatColumns: [
    {
      Name: 'FormatColumn-open_pr_count-205',
      Scope: {
        ColumnIds: ['open_pr_count'],
      },
      Style: {
        ForeColor: 'White',
        Alignment: 'Right',
      },
    },
  ],
},

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',
          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',
          PercentBarStyle: {
            CellRanges: [
              {
                Min: 5,
                Max: 1889,
                Color: 'purple',
              },
            ],
            CellText: ['CellValue', 'PercentageValue'],
          },
        },
        {
          ColumnId: 'closed_pr_count',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 'Col-Max',
                Color: 'blue',
              },
            ],
            ToolTipText: ['CellValue', 'PercentageValue'],
          },
        },
        {
          ColumnId: 'open_pr_count',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellText: ['CellValue'],
            CellTextPosition: 'Merged',
            CellRanges: [
              {
                Min: 'Col-Min',
                Max: 'Col-Max',
                Color: 'Brown',
              },
            ],
            BackColor: '#808080',
          },
        },
        {
          ColumnId: 'github_watchers',
          PercentBarStyle: {
            RangeValueType: 'Number',
            CellText: ['CellValue'],
            CellTextPosition: '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

Defining Percent Bars in Initial Adaptable State

Percent Bars are defined in Initial State as follows:

const initialState: InitialState = {
StyledColumn: {
    StyledColumns: [
      {
        ColumnId: 'github_stars',
        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',
          CellText: ['CellValue', 'PercentageValue'],
          CellTextPosition: 'Merged',
          ToolTipText: ['CellValue', 'PercentageValue'],
        },
      },
      {
        ColumnId: 'open_issues_count',
        PercentBarStyle: {
          ColumnComparison: {
            MinValue: 0,
            MaxValue: 'closed_issues_count',
            Color: 'Brown',
          },
        },
      },
    ],
  },
};

Provide ColumnId and add the Style

Supply ColumnId of Styled Column showing Percent Bar
Add a PercentBarStyle object

Specify the Type of Range

The RangeValueType property can take 2 values:

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

Note

This property is only required when using Ranges

Either Add Ranges...

Use CellRanges to add Ranges as needed; each Range has 3 properties:

Min - lower end of Range (number or 'Col-Min') Max - upper end of Range (number or 'Col-Max') Color - string property representing a Colour

Caution

Col-Min & Col-Max can only appear at ends of Range groups

...Or Provide a Column Comparison

This creates the Percent Bar using a comparison against another Column in the Grid.

Again Min, Max and Color values are required

Supply a Back Color

This colour will be used to colour that part of the cell which was not filled by the Percent Bar.

Provide Cell (and Tool Tip) Text and Cell Text Position

You can provide Text that will appear either (or both) in:

the Cell
as a ToolTip

Both Cell and ToolTip Text can include either or both of:

the Cell's actual value
a percentage value of the cell against the Range

You can also set how the Cell Text is positioned relative to the Percent Bar; there are 3 values:

Above
Below (the default)
Merged (the text is placed on top of the Percent Bar) )

Creating Percent Bars

Percent Bar Styles can be created at run-time using the UI wizard.

UI Step by Step Guide

Creating a Percent Bar Style

There are many stages when creating a Percent Bar Style:

Select Percent Bar

The 1st step of the Wizard displays the different Styled Column Types available.

Select Percent Bar

Select a Numeric Column

The 2nd step of the Wizard displays all the numeric columns available in AG Grid (which do not have a Styled Column)

Choose the Column you want to set a Style for

Create Percent Bar Style using Ranges...

The 3rd step of the Wizard is where the Style is created.

This will typically include one ore more Ranges.

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:

a value (i.e. a number either hard-coded or dynamically evaluated)
a percentage (e.g. top 50%)

Caution

You cannot mix and match Ranges; they need to be all Value or all Percentage based

There are 2 options for providing numbers in the Range:

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

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
But the Wizard only allows the automatic Min in the first Range and automatic Max in the last Range

.,.or Create Percent Bar 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 Percent Bar.

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

Configure Cell Display Properties

There are 4 options to set for how the cells in the Percent Bar will render:

Back Colour for the Bar
Cell Display - Cell Value or Percent Value
Cell Text Position - Above, Below or Merged
Tooltip Display - Cell Value or Percent Value

Provide Additional Settings

The next step of the Wizard displays some additional settings for the Percent Bar.

Currently there is only one option: whether to show the Percent Bar in Grouped Rows

By default Grouped Rows do not display Percent Bars (as aggregated values usually make no sense)

Check the box to enable this, if this is your required behaviour

Videos

Styled Column Min/Max Values

(Recorded with AdapTable v13.0)

Comparison Percent Bars

(Recorded with AdapTable v14.0)

Formatting Percent Bar text

(Recorded with AdapTable v15.0)

FAQ

Can we see the underlying value in a Percent Bar Style cell? Yes - via the CellText property which you set either at Design Time or at Run Time

Can we right align the cell value in a Percent Bar Style cell? Yes, that is done using standard Column Formatting which will decide how the text in the Percent Bar is rendered

PreviousGradient Style NextBadge Style

Framework: