Styled Columns

Badge Style

Summary

  • Badge Style decorates each cell value with one or more styled "pills" (labels)
  • Each pill is fully customisable — colours, border, font, shape and icon
  • Multiple Badges can be defined per column and selectively rendered using a Rule
  • Array columns render one pill per element (with spacing and overflow options)
  • Column-level options control inner padding, cell chrome behind the pills and alignment

The Badge Style renders the text of a Cell inside a "Badge" (sometimes known as a label).

The Badge can be fully styled, i.e. coloured, given a shape and border etc.

Caution

Badges can only be applied to Numeric, String or array (textArray / numberArray) columns

Multiple Badges can be provided for the same Column using Rules.

Badges can optionally include an Icon to display next to the text.

Hint

It is also possible to provide an Icon-only Badge where no text is displayed

Anatomy

A Badge Style is composed of one or more pills plus a set of column-level options.

Each pill has:

  • A PillStyle — back / fore / border colour, font weight / style, text decoration
  • A Shape — Pill, Rounded (default) or Square
  • The cell text rendered inside the pill
  • An optional IconProperties group — System or Custom Icon, drawn at the Start (default) or End of the pill (Position), with optional Gap and IconOnly
  • An optional Rule (Predicate or Expression) that decides whether the pill renders for a given cell

Note

  • Pills are evaluated top-down — the first matching Badge in the Badges array wins
  • For array columns (textArray / numberArray), AdapTable draws one pill per element

Column-level options on BadgeStyle apply to every pill in the column:

  • Density — inner padding preset (Compact / Normal / Comfortable)
  • Cell — chrome of the cell behind the pills (background, border, radius)
  • Font.Alignment — positions the badge row (Left / Center / Right) within the cell
  • Spacing and OverflowMode — how multiple pills lay out in array cells (gap; truncate / wrap / scroll)

Breaking Change

In AdapTable 23 a new PillStyle was introduced and improvements were made to radius, shape, and aligment

Badge Styled Columns
Fork
  • Overview demo — five columns in one grid (see the focused demos below for one idea per sandpack):
    • name — single gray pill (Density: Compact)
    • Language — icon-only pills per language (custom inline icons; no PillStyle)
    • License — three rules with different PillStyle colours
    • Closed Issues — three numeric rules with system icons (Density: Comfortable)
    • topics — array column: per-topic rules, default fallback pill, OverflowMode: Wrap

Badge UI Options

There are many options available to control the look and feel of the Badge (and the containing Cell).

Pill Style

Each Badge's pill is styled via the PillStyle property.

Hint

PillStyle is optional — when omitted, the Badge displays with default chrome (useful for icon-only Badges)

This is a cut-down subset of Adaptable Style containing just the properties that are relevant:

  • BackColor — pill background colour
  • ForeColor — pill text / icon colour
  • BorderColor — optional 1px pill border
  • FontWeight — 'Normal' or 'Bold'
  • FontStyle — 'Normal' or 'Italic'
  • TextDecoration — 'None', 'Underline', 'Overline' or 'LineThrough'

Note

  • Corner radius is not on PillStyle — use the Shape token instead
  • Pills inherit nothing from a Format Column; Styled Columns own their pill rendering completely

Shape

Each Badge can declare a Shape token instead of reaching for a pixel BorderRadius:

  • 'Pill' — fully rounded ends
  • 'Rounded' — subtly rounded corners (~4px)
  • 'Square' — sharp corners

Caution

Shape is the only way to set corner radius — PillStyle does not expose a BorderRadius property

{
  Shape: 'Pill',
  PillStyle: { BackColor: 'DarkBlue', ForeColor: 'white' },
}

Density

The Density property on BadgeStyle controls the inner padding for every badge in the column.

This ensures that a column reads as one consistent label set:

  • 'Compact' — tight padding for dense grids
  • 'Normal' — balanced (default)
  • 'Comfortable' — looser, for low-density / large-font grids
{
  ColumnId: 'topics',
  Name: 'Topics Badges',
  BadgeStyle: {
    Density: 'Compact',
    Badges: [/* ... */],
  },
}

Cell Style

The Cell property on BadgeStyle styles the chrome of the cell behind the pills — independently of the pills themselves.

It accepts a CellBoxStyle object with the standard cell-box properties:

  • BackColor — cell background colour
  • BorderColor — cell border colour
  • BorderRadius — cell corner radius (in pixels)

Note

  • Cell is optional — when unset, the cell inherits any matching Format Column Cell-box properties
  • When set, Cell claims the Cell slice: matching Format Column Cell-box properties are stripped so the two cannot fight
Badge Style: Cell & Alignment
Fork
  • License — column-level Cell (background, border, radius) behind the pills, plus Font.Alignment: 'Center' for the whole badge row
  • Three Predicate rules tint MIT / BSD / other licences — same pill styling idea as the overview demo, isolated here to show v23 column-level options

Row Alignment

By default the row of Badges in a cell flows from the left of the cell.

The Font.Alignment property on BadgeStyle positions the entire badge row horizontally within the cell:

  • 'Left' (default)
  • 'Center'
  • 'Right'

Note

  • Only Alignment is meaningful on the column-level Font for a Badge column
  • Other Font properties (ForeColor, FontWeight, etc.) belong on each pill's PillStyle, not here
  • When set, Font.Alignment overrides Alignment from any matching Format Column
{
  ColumnId: 'license',
  Name: 'License Badges',
  BadgeStyle: {
    Font: {
      Alignment: 'Center',
    },
    Badges: [/* ... */],
  },
}

Rules

Which pill is shown for each cell is decided by each badge's optional Rule — AdapTable walks the Badges array top-down and uses the first match.

A Rule can be supplied in either form:

  • Predicate — system or Custom Predicate (used in most demos today)
  • Expression — an AdaptableBooleanQuery when you need richer logic

If a badge has no Rule, it matches every cell — put exactly one such badge at the end of the array as a fallback (e.g. a default gray pill on an array column).

Hint

  • Multiple badges per column let you vary PillStyle, Shape and Icon by value
  • For instance, you can have a different colour per status or licence type
Badge Styles: Multiple Rules
Fork
  • This example contains a Badge Style on the Country column
  • Each country's Badge shows a different style based on a bespoke Rule

Icons

Badges can optionally include an Icon for extra decoration in addition to the Style.

They are defined using the IconProperties object which nests 4 main Icon-related properties:

PropertyDescription
IconThe Icon itself (of type Adaptable Icon and most commonly a System Icon)
Position'Start' (default value) or'End'
GapPixel gap between Icon and Pill text (falls back to column Density preset when omitted)
IconOnlySet to true to hide Pill text and show only the icon (see Icon Only Badges)

Breaking Change

  • Prior to AdapTable 23 these were four flat properties (Icon, IconPosition, IconGap, IconOnly) on the Badge
  • The Migration Helper updates existing configurations automatically

Icon Placement

The Position and Gap properties control where the icon sits in the pill and how much breathing room it gets:

IconProperties: {
  Icon: { name: 'alert' },
  Position: 'End',
  Gap: 6,
},
PillStyle: { BackColor: 'Red', ForeColor: 'white' },

Custom Icons

Alternatively, the Icon in the Badge can be a Custom Icon provided by the developer at design-time.

Custom Icons can be defined "inline" or supplied using the customIcons property in User Interface Options.

Hint

  • The advantages of using the customIcons property is that Icons can be re-used (e.g. in Buttons)
  • It also allows run-time users to create Badge Styles that use custom icons as they will appear in the icon dropdown
Badge Styles: Custom Icons
Fork
  • This example also contains a Badge Style on the Country column
  • Each country's Badge includes an icon that was provided in customIcons in User Interface Options

Icon Only Badges

It is possible to render a Badge where only the Icon is visible (without any cell text displayed).

This is done by setting IconProperties.IconOnly to true.

{
  IconProperties: {
    Icon: { name: 'star' },
    IconOnly: true,
  },
  PillStyle: { BackColor: 'Gold' },
}

Hint

  • Prior to AdapTable 23 this was the recommended way to display only an icon in an AdapTable Column
  • However the new Icon Styled Column supports this in a more powerful and intuitive way and includes presets
Badge Styles: Only Icons
Fork
  • This example contains 2 Badge Styles that display the Icon only (and no cell text):
    • Code - uses the same set of Custom Icons that we provide in the demo above (and has no style for the Badge applied)
    • Rating - uses an AdapTable Icon and does have a style (of gray back colour)

Arrays

Badges can be applied to multiple items in the same cell.

Caution

The Column definition needs to have a Cell Data Type of textArray or numberArray

By default AdapTable will apply the same Badge style to every item in the Array.

However users can create multiple Badges for an Array column, with each having its own Rule and Style.

Note

There is no limit for the number of Badges which an array-based Column can contain

Badge Styles: Arrays
Fork
  • This example applies a Badge Style to 2 array-based Columns:
    • Institutions column (string) - we created 7 Badges each with a Rule (per institution), and a (Green) Badge for institutions which do not meet any Predicate
    • Awards column (numeric) - a single Badge Style for all values (and no Rules)

Spacing & Overflow

When rendering multiple badges side-by-side, two further options are available:

  • Spacing (number, px — default 4) — sets the gap between adjacent badges
  • OverflowMode (default 'Truncate') — how badges lay out when the cell is too narrow:
    • 'Truncate' — single line; cell clips overflow (legacy behaviour)
    • 'Wrap' — wrap onto subsequent lines (works best with autoRowHeight or a tall rowHeight)
    • 'Scroll' — single line; the cell becomes horizontally scrollable
{
  ColumnId: 'topics',
  Name: 'Topics Badges',
  BadgeStyle: {
    Density: 'Compact',
    Spacing: 4,
    OverflowMode: 'Wrap',
    Badges: [/* ... */],
  },
}

Custom Predicates

The Badge Style can use a Custom Predicate in a Predicate rule when many values need grouping (e.g. region flags on an array column).

Hint

  • This is very useful if there are many different cell values and a lookup function is required
  • It is also useful in Array Columns where you wish to group similar values together
Badge Styles: Custom Predicates
Fork
  • This example applies a Badge to the Institutions column (similar to the demo above)
  • However we also create 4 Custom Predicates for UK, US, European and Asian institutions
  • We have created 4 Badges - one for each Custom Predicate - which displays an appropriate flag

Defining Badge Styles

Badge Styles are provided at design-time through Styled Column Initial Adaptable State.

Developer Guide

Providing a Badge Style in Styled Column State

const initialState: InitialState = {
  StyledColumn: {
    StyledColumns: [
      {
        ColumnId: 'closed_issues_count',
        Name: 'Closed Issues Badges',
        BadgeStyle: {
          Density: 'Compact',
          Badges: [
            {
              Predicate: {
                PredicateId: 'LessThan',
                Inputs: [1000],
              },
              Shape: 'Pill',
              IconProperties: {
                Icon: {
                  name: 'alert',
                },
                Position: 'Start',
              },
              PillStyle: {
                BackColor: 'Red',
                ForeColor: 'white',
              },
            },
            {
              Predicate: {
                PredicateId: 'LessThan',
                Inputs: [10000],
              },
              Shape: 'Rounded',
              IconProperties: {
                Icon: {
                  name: 'flag',
                },
              },
              PillStyle: {
                BackColor: 'Orange',
                ForeColor: 'white',
              },
            },
            {
              Shape: 'Square',
              IconProperties: {
                Icon: {
                  name: 'checked',
                },
              },
              PillStyle: {
                BackColor: 'Green',
                ForeColor: 'white',
              },
            },
          ],
        },
      },
    ],
  },
};
1
Provide ColumnId, Name and add the Badge Style

Supply 3 mandatory properties:

  • ColumnId — Id of Column on which the Badge Style should render
  • Name — a unique name for the Styled Column
  • BadgeStyle object — wrapper containing Badge configuration
2
Configure column-level Badge Style

The BadgeStyle object accepts several column-wide options that apply to every badge in the column:

  • Density — inner padding: 'Compact', 'Normal', 'Comfortable'
  • OverflowMode (array columns) — how badges lay out when a cell is too narrow: 'Truncate' (default), 'Wrap' or 'Scroll'
  • Cell — CellBoxStyle (background, border, radius) drawn behind the pills
  • Font.Alignment — positions the badge row (Left / Center / Right) within the cell; overrides any matching Format Column alignment
  • Spacing (array columns) — pixel gap between adjacent Badges
3
Provide an Array of Badges

The Badges array contains each distinctly styled Badge in the Column.

Each Badge has its own optional Rule, Shape, Pill Style and Icon.

Note

Badges are evaluated top-down — first matching Badge in array wins

4
Provide a Rule (optional)

Each badge can include a Predicate or Expression. If omitted, the badge matches every cell (use once, as the last entry, for a fallback pill).

5
Choose a Shape and Pill Style

Use the Shape token to control the pill's corner radius:

  • 'Pill' — fully rounded ends
  • 'Rounded' (default) — subtly rounded corners (~4px)
  • 'Square' — sharp corners

Caution

Shape is only way to set corner radius (not available in PillStyle)

Use PillStyle for the pill's visual properties (subset of Adaptable Style):

Note

  • Pills don't inherit from Format Column
  • Pill font size is controlled by column Density, not PillStyle
6
Supply Icon Properties (optional)

Display an icon inside the pill via the IconProperties group:

  • IconProperties.Icon (required when the group is present) — an Adaptable Icon. Either an AdapTable System icon (e.g. { name: 'alert' }) or a Custom icon provided inline or via customIcons
  • IconProperties.Position — 'Start' (default) or 'End'
  • IconProperties.Gap — pixel gap between the icon and the pill text (falls back to the column Density preset when omitted)
  • IconProperties.IconOnly — true to hide the cell text and show only the icon

Creating Badge Styles

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

UI Step by Step Guide

Creating a Badge Style using the Styled Column Wizard

FAQ

Can we create multiple Badge Styles? Yes, you can have as many per column as required; each should have its own, non-overlapping, Predicate- or Expression-based Rule.

Can I have differently styled Badges on the same array cell? Yes — Badges on array columns (textArray / numberArray) work the same way as on scalar columns: each BadgeStyleDefinition has its own PillStyle, Shape, Icon and Rule, and AdapTable picks the first matching Badge per array element.

Do you support Badges on Date Columns? Not currently, but we might add this in a future version if there is demand

PreviousPercent Bar StyleNextSparkline Column Style