Display Format

Summary

Display Formats are used to format the text displayed in Cells
AdapTable provides a number of System Display Format Options that can be configured for:
- Numeric columns (with named presets or full formatter options)
- Date columns (with pattern-based formats and wizard presets)
- String columns
Additionally developers can provide their own Custom Display Formats
Conditions can be added so that only cells with meet the Rule are formatted
AdapTable also provides Presets (for Numeric and Date columns) as a convenience feature

Format Columns can be provided with a Display Format.

This defines how the value in each cell in the column is formatted.

Hint

Provide a Column Formatting Condition if you want the Display Format only to apply when a rule is met

Note

Setting a Display Format does not change the underlying cell value

AdapTable provides 3 sets of System Display Formats, based on the data type of the Column:

Hint

AdapTable also provides Numeric and Date presets for commonly-added Formats

In addition developers can provide Custom Display Formats if the System Display Formats are insufficient.

Caution

When a Display Format is applied, any Column Filters will be evaluated on the column's underlying (i.e. raw) value

Defining Display Formats

Display Formats are defined on Format Columns in initialState.FormatColumn.FormatColumns.

Each entry needs a Name, a Column Scope (Scope), and a DisplayFormat — either a formatter object or (numeric columns only) a preset name.

Developer Guide

Providing Display Formats in Initial State

const initialState: InitialState = {
  FormatColumn: {
    FormatColumns: [
      {
        Name: 'formatColumn-name',
        Scope: {
          ColumnIds: ['name'],
        },
        DisplayFormat: {
          Formatter: 'StringFormatter',
          Options: {
            Case: 'Upper',
          },
        },
      },
      {
        Name: 'formatColumn-created_at',
        Scope: {
          ColumnIds: ['created_at'],
        },
        DisplayFormat: {
          Formatter: 'DateFormatter',
          Options: {
            Pattern: 'yyyy/MM/dd',
          },
        },
      },
      {
        Name: 'formatColumn-week_issue_change',
        Scope: {
          ColumnIds: ['week_issue_change'],
        },
        DisplayFormat: 'Accounting',
      },
      {
        Name: 'formatColumn-github_stars',
        Scope: {
          ColumnIds: ['github_stars'],
        },
        DisplayFormat: {
          Formatter: 'NumberFormatter',
          Options: {
            FractionDigits: 1,
            Multiplier: 0.001,
            Suffix: 'K',
          },
        },
      },
    ],
  },
};

Add Format Columns to Initial State

Create one or more objects under FormatColumn.FormatColumns. Each targets columns via Scope and sets how cell text is rendered.

Specify Name and Scope

Each Format Column object needs a unique Name

It also needs Scope defined - where it is applied

Configure Display Format

Provide DisplayFormat to tell AdapTable to create a format rather than a Style

String Display Format

Use Formatter: 'StringFormatter' and Options (e.g. Case, Prefix or Trim).

Here name is shown in uppercase.

There are no presets available for String Columns.

Date Display Format

Use Formatter: 'DateFormatter' with Options.Pattern (Unicode date field symbols).

Here created_at uses yyyy/MM/dd.

There are no configuration presets available for Date Columns.

Numeric Display Format (preset)

For common numeric layouts, you can set DisplayFormat to a preset name (e.g. 'Accounting').

AdapTable resolves it to a NumberFormatter at runtime.

Here week_issue_change shows negatives in parentheses (Accounting preset).

Numeric Display Format (formatter options)

When no preset fits, supply the full object: Formatter: 'NumberFormatter' and the options you need (Multiplier, Suffix, FractionDigits, etc.).

Here github_stars is scaled to thousands with a K suffix — not the same as the 'Thousand' preset (different fraction digits).

Column Formatting: Display Formats

Fork Fork

This example shows four Display Formats (see Defining Display Formats above):
- Name — string (Case: 'Upper')
- Created — date (Pattern: 'yyyy/MM/dd')
- Issue Change — numeric preset ('Accounting')
- Github Stars — numeric options (Multiplier + K suffix)

Display Format Presets

AdapTable provides presets for numeric and date columns.

For Date columns, presets is a purely UI convenience feature allowing run-time users to quickly apply the datetime pattern they require in the UI wizard.

For Numeric columns, presets can be used in 2 ways:

as a convenience feature for run-time users to quickly apply a display format (similar to dates)
as a configuration option for developers who can reference the preset by name when defining the object

Find Out More

See Using Date Presets and Using Numeric Presets for more information

Display Format Precedence

Display Formats follow the same rules as general Column Formatting Precedence.

Namely, the Display Formats are evaluated in the order they are provided in Initial Adaptable State or the UI.

Hint

This allows you create multiple display formats for the same column which will be evaluated in the order provided

Column Formatting: Format Precedence

Fork Fork

In this demo we provide 2 Display Formats - each with a Condition - both on the Github Stars Column:
- Any cells > 1,000,000 will display as xM
- Any cells > 1,000 will display as xK
- Any cells under 1000 will display normally
Note: We need to put the 'Million' condition first, as otherwise only the Thousand condition will display

Deep Dive

How AdapTable applies Display Formats

Display Formats are a presentation layer.

They change the text AG Grid renders in a cell; the value held on the row (and used for most filter logic) stays the same.

AG Grid Integration

When a column has one or more active Format Columns with DisplayFormat set, AdapTable wires AG Grid’s valueFormatter on that column’s ColDef.

Note

AdapTable does not create a separate AG Grid formatter per Format Column
There is one valueFormatter on the column; it delegates to AdapTable for each cell

If no Format Column with DisplayFormat applies to that column, any valueFormatter you supplied in your own columnDefs is left unchanged.

What happens on each cell render?

For every cell the formatter does 4 things:

Loads active Format Columns for that column that include a DisplayFormat
Picks the most relevant Format Column — as per the Display Format Precedence Rules described above
Calls resolveDisplayFormat on that column’s DisplayFormat value
Runs the resolved formatter (NumberFormatter, DateFormatter, or StringFormatter) via AdapTable’s internal formatting helpers to produce the display value

Format Column (state)
  → AG Grid valueFormatter (per column)
    → most relevant Format Column for this cell
    → resolveDisplayFormat (preset name → AdaptableFormat object)
    → system formatter (+ optional custom handlers) → display text

Resolving presets and formatter objects

DisplayFormat in Format Column state is either:

A numeric preset name (e.g. 'Dollar') — stored as a string. At render time AdapTable displays it appropriately

Caution

State is not rewritten unless the user edits the format in the UI (which typically persists the long form)

A full AdaptableFormat object — { Formatter: '…', Options: { … } } for number, date, or string. Used as-is

Date columns always use the object form in state (DateFormatter + Pattern).

Note

Date “presets” in the wizard only fill in Pattern; they are not preset names on DisplayFormat

Custom Display Formats

If you register Custom Display Formats in Format Column options, their ids can appear on Options.CustomDisplayFormats.

Those handlers run in the same formatting pipeline after the system formatter options are applied.

API usage

The API method formatColumnApi.getDisplayFormatForColumn returns the resolved AdaptableFormat for a column (preset names are expanded there too).

This is useful when building summaries, tooltips, or other UI that should match grid display.

FAQ

Does a Display Format change the cell's underlying value? No. Formatting is display-only; sorting, filtering, and export still use the raw value unless your pipeline applies formatting separately. See How AdapTable applies Display Formats for the runtime path.

Can a Display Format apply only to some cells in a column? Yes. Add a Column Formatting Condition on the Format Column so the Display Format runs only when the rule matches.

Can we define more than one Display Format on the same column? Yes. Provide multiple Format Columns on that column (with different conditions if needed). They are evaluated in state order — see Display Format Precedence above.

Do Column Filters use the formatted text or the raw value? Filters evaluate the underlying value, not the formatted string shown in the cell.

What are Display Format presets?

Numeric: named values (e.g. DisplayFormat: 'Dollar') that AdapTable expands into a NumberFormatter at runtime. See Numeric Display Format.
Date: common patterns in the wizard (e.g. HH:mm:ss); in state you still set Options.Pattern. See Date Display Format.
String: no presets — use StringFormatter options directly.

When should I use a preset vs a full formatter object? Use a numeric preset when one of the built-in names matches what you need (currency, Percentage, Thousand, Accounting, etc.). Use a full NumberFormatter / DateFormatter / StringFormatter object when you need a bespoke combination (e.g. Prefix: 'EUR ', Multiplier: 0.01, and a custom suffix — not covered by a single preset).

Can we provide our own formats if the system options are not enough? Yes. Register Custom Display Formats in Format Column options and reference them from a Format Column (added in Version 12).

AdapTable Resources

PreviousFormatting & Styling NextNumeric Format