React Embedded AnalyticsData Types

Studio supports a variety of data types. Instead of being defined directly on fields, data types are defined on Formats. A Format controls formatting along with other behaviour.

const fields = [
    {
        id: 'athlete',
        format: 'textFormat' // textFormat uses the `string` data type
    },
    // ... other fields
];

When using Synchronous Data Sources and not providing fields, the format will be Inferred from the Data.

Data Types Copy Link

Each of the data types are described in the table below. The input type is the JavaScript type that is supported in the source data. The default Format is the Format that will be used when inferring fields.

For data and datetime, the string value is expected to be in ISO-8601 format, and the number value is Unix epoch.

Formats Copy Link

Provided Formats Copy Link

Each display format can be changed via the Format Options. It is possible to Override the Provided Formats globally or for individual fields.

Inferring Formats Copy Link

When using Synchronous Data Sources and not providing fields, the format is inferred from the data. Inference is based on the first non-null value in the data.

number values will be inferred as integerFormat if the first value is an integer, otherwise as decimalFormat.

Date values will be inferred as dateTimeFormat.

When dates are represented as strings, they will be inferred as dateFormat if there is no time component, otherwise as dateTimeFormat.

Format Options Copy Link

All the formats with number data type use Intl.NumberFormat to perform the default formatting. This is set in the field/format options as format. This allows control over the number of decimal places plus many other things. E.g. currencyFormat will not show a currency by default, but the currency can be set in the Intl.NumberFormat object.

Similarly, dateFormat and dateTimeFormat use Intl.DateTimeFormat in options.format.

See below for examples demonstrating how to customise this.

Overriding Provided Formats Copy Link

Provided Formats can be overridden by passing the result of the createFormats function to the formats property of the data sources definition.

The overrides allow you to change any of the Format Properties (except the data type).

const data = useMemo(() => { 
	return {
        formats: createFormats({
            overrides: {
                textFormat: {
                    valueFormatter: ({ value }) => value.toUpperCase(),
                },
                currencyFormat: {
                    options: {
                        format: new Intl.NumberFormat(undefined, {
                            style: 'currency',
                            currency: 'GBP',
                            currencyDisplay: 'narrowSymbol',
                            maximumFractionDigits: 2,
                        }),
                    },
                },
            },
        }),
        // sources, etc.
    };
}, []);

<AgStudio data={data} />

It is also possible to override all of the value formatting/serializing properties for individual fields by setting them on the field definition.

const data = useMemo(() => { 
	return {
        sources: [{
            fields: [{
                id: 'salePrice',
                options: {
                    format: new Intl.NumberFormat(undefined, {
                        style: 'currency',
                        currency: 'USD',
                        currencyDisplay: 'narrowSymbol',
                        maximumFractionDigits: 2,
                    }),
                },
                // other field properties
            }]
            // other source properties
        }],
    };
}, []);

<AgStudio data={data} />

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

Providing Custom Formats Copy Link

Custom Formats can be created by passing the result of the createFormats function to the formats property of the data sources definition. The custom Formats are set via the additionalTypes property. See the Format API for the list of properties that can be set on a custom Format.

If using Typescript, the custom Formats should be defined within a type that extends AgFormats and passed to the TFormats generic type parameter of the data source and field types, as well as the createFormats function.

interface CustomFormats extends AgFormats {
    myCustomFormat: AgFormatDefinition<'number'>;
}

const data = useMemo(() => { 
	return {
        formats: createFormats({
            additionalTypes: {
                myCustomFormat: {
                    dataType: 'number',
                    supportedRoles: ['numeric', 'category'],
                    supportedAggregations: ['sum'],
                    serializer: (value) => value,
                    deserializer: (value) => value,
                    valueFormatter: ({ value }) => `*${value}*`,
                    blankValue: '-',
                },
            },
        }),
        // sources, etc.
    };
}, []);

<AgStudio data={data} />

Format API Copy Link