---
title: "Formatting"
framework: angular
version: "2.1.2"
---

# Formatting

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

| Format | Data Type | Default Display Format |
| --- | --- | --- |
| `textFormat` | `string` | `Text Value` |
| `integerFormat` | `number` | `100,000` |
| `decimalFormat` | `number` | `123.00` |
| `booleanFormat` | `boolean` | `True` / `False` (or [Locale](https://www.ag-grid.com/studio/angular/localisation/) 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` |

#### Formatting

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Formatting](https://www.ag-grid.com/studio/examples/formatting/formatting-overview/angular/)

## Format Options

The `formatOptions.format` property on a field accepts a [Format String](#format-strings):

```ts
<ag-studio
    [data]="data"
    /* other studio properties ... */ />

this.data = {
    sources: [{
        fields: [
            { id: 'priceGBP', format: 'currencyFormat', formatOptions: { format: '£#,##0.00' } },
            { id: 'discount', format: 'percentageFormat', formatOptions: { format: '#,##0.0%' } },
            { id: 'orderDate', format: 'dateFormat', formatOptions: { format: 'dd mmm yyyy' } },
        ],
    }],
};
```

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

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.

#### Number Tokens

| 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 `0`s 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` |

#### Date and Time Tokens

| 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` |

#### Format Options

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Format Options](https://www.ag-grid.com/studio/examples/formatting/format-options/angular/)

### Conditional Formatting

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";#,##0
```

Without 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

#### Overriding Formats

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Overriding Formats](https://www.ag-grid.com/studio/examples/formatting/overriding-formats/angular/)

A field can override any of its Format's value-formatting and serialising properties directly on its definition:

```ts
<ag-studio
    [data]="data"
    /* other studio properties ... */ />

this.data = {
    sources: [{
        fields: [{
            id: 'salePrice',
            format: 'currencyFormat',
            formatOptions: { format: '$#,##0.00' },
        }],
    }],
};
```

The following Format properties can be set directly on the field definition:

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `serializer` | `AgFieldSerializer<InferDataTypeFromFormat<TRegistry, TFormat>>` |  | Optional. How the field values will be serialized into state. Defaults to format serializer. |
| `deserializer` | `AgFieldDeserializer<InferDataTypeFromFormat<TRegistry, TFormat>>` |  | Optional. How the field values will be deserialized from state. Defaults to format deserializer. |
| `createValueFormatter` | `AgFieldValueFormatterFactory<InferDataTypeFromFormat<TRegistry, TFormat>, TFormatOptions, any>` |  | Optional. Build a value formatter bound to the field's format options and the runtime API. Defaults to format factory. |
| `blankValue` | `string` |  | Optional. How blank values will be displayed. Defaults to format blank value. |
| `formatOptions` | `TFormatOptions` |  | 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](#format-api) except the data type:

```ts
<ag-studio
    [data]="data"
    /* other studio properties ... */ />

this.data = {
    formats: createFormats({
        overrides: {
            textFormat: {
                createValueFormatter: () => (value) => value.toUpperCase(),
            },
            currencyFormat: {
                formatOptions: { format: '£#,##0.00' },
            },
        },
    }),
};
```

## Custom Formats

#### Custom Formats

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Custom Formats](https://www.ag-grid.com/studio/examples/formatting/custom-formats/angular/)

Custom Formats are added by passing `additionalTypes` to `createFormats`. See the [Format API](#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](https://www.ag-grid.com/studio/angular/registry-type/):

```
type CustomFormats = AgFormats & {
    myCustomFormat: AgFormatDefinition<'number'>;
}

interface CustomRegistry extends AgDefaultRegistry {
    formats: CustomFormats;
}
```

```ts
<ag-studio
    [data]="data"
    /* other studio properties ... */ />

this.data = {
    formats: createFormats<CustomRegistry>({
        additionalTypes: {
            myCustomFormat: {
                dataType: 'number',
                supportedRoles: ['numeric', 'category'],
                supportedAggregations: ['sum'],
                serializer: (value) => value,
                deserializer: (value) => value,
                createValueFormatter: () => (value) => `*${value}*`,
                blankValue: '-',
            },
        },
    }),
};
```

## Format API

Properties available on the `AgFormatDefinition&lt;TDataType extends AgDataType = AgDataType, TFormatOptions = any&gt;` interface.

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `dataType` | `TDataType` |  | The data type. |
| `supportedRoles` | `AgFieldRole[]` |  | How fields of this format can be used within widgets. Ordered by preference. |
| `supportedAggregations` | `AgAggregationFunction[]` |  | The supported aggregations for fields of this format. |
| `serializer` | `AgFieldSerializer<TDataType>` |  | How the field values will be serialized into state. |
| `deserializer` | `AgFieldDeserializer<TDataType>` |  | How the field values will be deserialized from state. |
| `createValueFormatter` | `AgFieldValueFormatterFactory<TDataType, TFormatOptions>` |  | Build a value formatter bound to the field's options and the runtime API. Called once per field at hydration. |
| `supportedBuckets` | `string[]` |  | The buckets that fields will support. |
| `blankValue` | `string` |  | How blank values will be displayed. |
| `formatOptions` | `TFormatOptions` |  | Optional. Will be passed to the value formatter. |