Applying Display Formats

View as Markdown

Summary

  • Display Formats control the text shown in cells without changing the underlying value
  • Built-in formatters cover numeric, string, and date columns (with wizard presets on number and date)
  • Template display formats interpolate [value], [column], and [rowData.x]
  • Custom display formatters are registered in formatColumnOptions.customDisplayFormatters and referenced by id
  • An optional Format Column Condition limits when a format applies

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

Display format typeWhen to use
Numeric Display FormatDecimals, separators, prefixes, named presets (currency, percent, …)
String Display FormatCase, trim, prefix/suffix
Date Display FormatPattern or date presets
Display Format using TemplatesRich labels mixing column name, cell value, and other row fields
Custom Display FormatCode-driven formatting when built-in formatters are not enough

Hint

Numeric and Date pages document presets for common patterns in the wizard and in state.

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',
          },
        },
      },
    ],
  },
};
1
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.

2
Specify Name and Scope

Each Format Column object needs a unique Name

It also needs Scope defined - where it is applied

3
Configure Display Format

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

4
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.

5
Date Display Format

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

Here created_at uses yyyy/MM/dd.

Date Columns have no named configuration presets (unlike Numeric). The wizard offers Pattern shortcuts; in state you set Options.Pattern.

6
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).

7
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
  • 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)
Loading demo…

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
  • 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
Loading demo…
Deep Dive

How AdapTable applies Display Formats

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.

AdapTable Resources