Vue Embedded AnalyticsFormatting

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 Options Copy Link

The formatOptions.format property on a field accepts a Format String:

<ag-studio
    :data="data"
    /* other studio properties ... */>
</ag-studio>

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

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.

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";#,##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 Copy Link

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

<ag-studio
    :data="data"
    /* other studio properties ... */>
</ag-studio>

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

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

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:

<ag-studio
    :data="data"
    /* other studio properties ... */>
</ag-studio>

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

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;
}

<ag-studio
    :data="data"
    /* other studio properties ... */>
</ag-studio>

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 Copy Link