Format digits in JSON components

All declarative (JSON) UI components available in the UI component library include support for automatically formatting dates and digits based on the user's preferred locale. This topic explains how you can configure these components to select which parts of a date to display or how many decimal digits to display to end-users.

Copy link to this section

Understand the formatting pattern

All field-based UI components, components that fetch and render values from persistable Types, support value formatting through a format field. This field appears inside the component’s dataSpec and controls how a specific part of the UI renders the data.

The structure follows a consistent pattern:

{Component}.dataSpec.{part}.format

To understand this pattern, open the Type definition for the component you want to configure. For example, to format values in a data grid, inspect the UiSdlDataGrid Type. This Type mixes UiSdlBaseDataGrid and exposes a dataSpec field. Inside UiSdlDataGridDataSpec, you can find the columnFields array. Each item in that array uses the UiSdlDataGridDataSpecColumnFieldSetting Type, which defines a format field.

The format field uses the Type UiSdlDynamicValueSpecParamFormat, a polymorphic format wrapper. You can configure this field with one of two specific subtypes depending on the kind of value you want to format:

• Use UiSdlNumberParamKindFormat for numeric values such as prices, percentages, and quantities.
• Use UiSdlDateTimeParamKindFormat for date and time values.

Each subtype defines a spec field where you configure formatting options, such as decimal precision or timestamp components.

Once you understand how to read these Types, you can find the format location for any field-based component by tracing the dataSpec field and inspecting the structure of its fields. The pattern stays consistent across components: identify the part of the component that displays a field, locate its format field, and set it using one of the supported format Types.

Copy link to this section

Format digits in a list component

Use UiSdlNumberParamKindFormat to define how numeric values appear.

1. Use a component like UiSdlCollectionList.
2. Add the dataSpec field.
3. Set the format on the relevant field.

{
  "type": "UiSdlConnected<UiSdlCollectionList>",
  "component": {
    "dataSpec": {
      "dataType": "WindTurbine",
      "primaryValueField": {
        "fieldName": "output",
        "format": {
          "type": "UiSdlNumberParamKindFormat",
          "spec": {
            "style": "decimal",
            "maximumFractionDigits": 2
          }
        }
      }
    }
  }
}

Set the style to "decimal". Adjust the precision with maximumFractionDigits.

Copy link to this section

Format dates in a list component

Use UiSdlDateTimeParamKindFormat to define how date values appear.

1. Use a component like UiSdlCollectionList.
2. Add the dataSpec field.
3. Set the format on the relevant field.

{
  "type": "UiSdlConnected<UiSdlCollectionList>",
  "component": {
    "dataSpec": {
      "dataType": "WindTurbine",
      "primaryValueField": {
        "fieldName": "date",
        "format": {
          "type": "UiSdlDateTimeParamKindFormat",
          "spec": {
            "year": "numeric",
            "month": "numeric",
            "day": "numeric",
            "hour": "numeric",
            "minute": "numeric",
            "second": "numeric",
            "timeZoneName": "long"
          }
        }
      }
    }
  }
}

Customize the output by combining options like month: "short", weekday: "long", or hour12: true. Choose the level of detail that best fits your use case.

Copy link to this section

Set display time zone in a chart

Some components allow you to control how dates render by setting an explicit time zone. These components mix in the UiSdlWithTimeZone Type, which includes a timeZone field.

To apply a time zone, set the timeZone field directly in the component’s JSON definition.

{
  "type": "UiSdlConnected<UiSdlLineBarChart>",
  "component": {
    "title": "Time Zone Chart",
    "dataType": "WindTurbine",
    "timeZone": "America/New_York"
  }
}

You can choose any valid IANA time zone, such as "America/New_York" or "Asia/Tokyo". To validate the time zone string, use the helper function isValidTimeZoneId().

To confirm whether a component supports time zone configuration, inspect its Type definition and check whether it mixes in UiSdlWithTimeZone. For example, UiSdlLineBarChart supports this field because it mixes that interface.