Applying Display Formats
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.customDisplayFormattersand 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 type | When to use |
|---|---|
| Numeric Display Format | Decimals, separators, prefixes, named presets (currency, percent, …) |
| String Display Format | Case, trim, prefix/suffix |
| Date Display Format | Pattern or date presets |
| Display Format using Templates | Rich labels mixing column name, cell value, and other row fields |
| Custom Display Format | Code-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',
},
},
},
],
},
};Create one or more objects under FormatColumn.FormatColumns. Each targets columns via Scope and sets how cell text is rendered.
Each Format Column object needs a unique Name
It also needs Scope defined - where it is applied
Provide DisplayFormat to tell AdapTable to create a format rather than a Style
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.
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.
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).
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).
- 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+Ksuffix)
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
- In this demo we provide 2 Display Formats - each with a Condition - both on the
Github StarsColumn:- 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
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 aNumberFormatterat runtime. See Numeric Display Format. - Date: common patterns in the wizard (e.g.
HH:mm:ss); in state you still setOptions.Pattern. See Date Display Format. - String: no presets — use
StringFormatteroptions 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.