Every field has a Format that controls how its values are displayed. Each provided Format applies a sensible default, and formatOptions.format overrides that default with either an Excel-style format string or - for numeric and date Formats - an Intl instance.
Provided Formats Copy Link
| Format | Data Type | Default Display Format |
|---|---|---|
textFormat | string | Text Value |
integerFormat | number | 100,000 |
decimalFormat | number | 123.00 |
booleanFormat | boolean | True / False (or Locale equivalent) |
dateFormat | date | 31/12/2025 (or equivalent for user's locale) |
dateTimeFormat | datetime | 31/12/2025, 13:00:00 (or equivalent for user's locale/timezone) |
percentageFormat | number | 50% |
currencyFormat | number | 123.00 |
Format Options Copy Link
The formatOptions.format property on a field accepts a Format String:
const studioProperties = {
data: {
sources: [{
fields: [
{ id: 'price', format: 'currencyFormat', formatOptions: { format: '£#,##0.00' } },
{ id: 'discount', format: 'percentageFormat', formatOptions: { format: '#,##0.0%' } },
{ id: 'orderDate', format: 'dateFormat', formatOptions: { format: 'dd mmm yyyy' } },
],
}],
},
// other studio properties ...
}Numeric and date Formats also accept an Intl.NumberFormat or Intl.DateTimeFormat instance, for cases where locale-aware formatting is required. Format strings are preferred for everything else.
Format Strings Copy Link
Format strings follow Excel's number-format syntax with a few extensions. The same syntax handles numeric, date, date-time, text, and boolean data types.
| Token | Meaning |
|---|---|
0 | Mandatory digit (zero-padded). |
# | Optional digit. |
. | Decimal separator. |
, | Thousands separator. A trailing , with no digit placeholder after it divides by 1,000. |
% | Multiply by 100 and append %. |
‰ | Multiply by 1,000 and append ‰. |
E+0 / E-0 | Scientific notation. The 0s set the minimum exponent width. |
"…" | Literal text. |
\x | Literal escape for a single character. |
@ | Text placeholder (string values). |
Common patterns:
| String | Output |
|---|---|
0 | 1235 |
0.00 | 1234.50 |
#,##0.00 | 1,234.50 |
#,##0,"k" | 1k |
0.00% | 123450.00% |
0.00E+00 | 1.23E+03 |
| Token | Meaning | Example |
|---|---|---|
yy / yyyy | 2- or 4-digit year | 25 / 2025 |
qq | Quarter | 1 |
m / mm / mmm / mmmm / mmmmm | Month: number, padded number, short name, long name, initial | 3 / 03 / Mar / March / M |
d / dd / ddd / dddd | Day: number, padded number, short name, long name | 5 / 05 / Wed / Wednesday |
ww / www | ISO week number, padded | 1 / 01 |
h / hh | Hour | 9 / 09 |
m / mm | Minute (when preceded by h or followed by s) | 5 / 05 |
s / ss | Second | 5 / 05 |
am/pm / a/p | Meridiem. Presence switches the hour token to 12-hour | PM / P |
Conditional Formatting Copy Link
A format string can combine multiple patterns separated by ;. Pattern can be prefixed with a condition in square brackets (e.g. [>1000]) to control when it applies, with the first match being the one used to format the value. The available comparators are >, >=, <, <=, =, and <>.
[>1000000]#,##0.0,,"M";[>1000]#,##0.0,"K";#,##0Without explicit conditions, the first two or three patterns apply to positive, negative, and zero values when formatting numbers; and the first two patterns apply to true and false when formatting booleans:
#,##0.00;(#,##0.00);"-""Yes";"No" Overriding Provided Formats Copy Link
A field can override any of its Format's value-formatting and serialising properties directly on its definition:
const studioProperties = {
data: {
sources: [{
fields: [{
id: 'salePrice',
format: 'currencyFormat',
formatOptions: { format: '$#,##0.00' },
}],
}],
},
// other studio properties ...
}The following Format properties can be set directly on the field definition:
Optional. How the field values will be serialized into state. Defaults to format serializer. |
Optional. How the field values will be deserialized from state. Defaults to format deserializer. |
Optional. Build a value formatter bound to the field's format options and the runtime API. Defaults to format factory. |
Optional. How blank values will be displayed. Defaults to format blank value. |
Optional. Will be passed to the value formatter. |
To change the default for a built-in Format across every field that uses it, pass the result of createFormats to the formats property of the data sources definition. The overrides accept any of the Format Properties except the data type:
const studioProperties = {
data: {
formats: createFormats({
overrides: {
textFormat: {
createValueFormatter: () => (value) => value.toUpperCase(),
},
currencyFormat: {
formatOptions: { format: '£#,##0.00' },
},
},
}),
},
// other studio properties ...
} Custom Formats Copy Link
Custom Formats are added by passing additionalTypes to createFormats. See the Format API for the full list of properties.
If using Typescript, define as a type that includes AgFormats (note that it must be a type, not an interface) and set as formats on the Registry Type:
type CustomFormats = AgFormats & {
myCustomFormat: AgFormatDefinition<'number'>;
}
interface CustomRegistry extends AgDefaultRegistry {
formats: CustomFormats;
}const studioProperties = {
data: {
formats: createFormats<CustomRegistry>({
additionalTypes: {
myCustomFormat: {
dataType: 'number',
supportedRoles: ['numeric', 'category'],
supportedAggregations: ['sum'],
serializer: (value) => value,
deserializer: (value) => value,
createValueFormatter: () => (value) => `*${value}*`,
blankValue: '-',
},
},
}),
},
// other studio properties ...
} Format API Copy Link
Properties available on the AgFormatDefinition<TDataType extends AgDataType = AgDataType, TFormatOptions = any> interface.
The data type. |
How fields of this format can be used within widgets. Ordered by preference. |
The supported aggregations for fields of this format. |
How the field values will be serialized into state. |
How the field values will be deserialized from state. |
Build a value formatter bound to the field's options and the runtime API. Called once per field at hydration. |
How blank values will be displayed. |
Optional. Will be passed to the value formatter. |