Skip to content
Kumiko

Field formatting

ForApp developer
LevelBeginner

In plain words

Section titled “In plain words”

A field can say how its value should look on screen without the stored value changing at all. You write that rule as plain data in a screen column or detail field, for example “show this number as an area in square metres”. The renderer uses the active locale, so 58 can appear as 58 m² while the stored value remains 58.

FormatSpec at a glance

Section titled “FormatSpec at a glance”

Screens format values declaratively on the client without changing the stored value. A column or detail field carries a JSON-safe renderer format spec, which the renderer applies at display time.

The built-in format keys are a closed, typed set (FieldFormatRegistry): timestamp, date, boolean, currency, priority, number, decimal, bigInt, unit, enumOption, json.

This page focuses on the two formats that usually need explicit configuration: unit and enumOption. The other keys use their field metadata or the options shown in the generated FieldFormatRegistry types and tests.

unit

Section titled “unit”

Format a number with a unit, CLDR/Intl.NumberFormat-correct per locale:

{ format: "unit", unit: "m2", unitDisplay: "short" } // "58 m²"
  • unit is a closed set: "m2" | "km" | "m" | "kg" | "percent" | "mi".
  • unitDisplay: "long" | "short" | "narrow".
  • Note: style:"unit" with unit:"percent" does not multiply by 100 (unlike style:"percent"), percent-as-unit is raw-fractional.

enumOption

Section titled “enumOption”

Resolve an enum value into a translated label client-side:

{ format: "enumOption", keyPrefix: "jobs:entity:job:field:status:option:" }
  • The i18n key is <keyPrefix><value>. Prefer fieldOptionLabelKeyPrefix() from @cosmicdrift/kumiko-renderer/headless over a hand-written prefix.
  • Falls back to the raw value when the key isn’t translated (same rule as buildOptionLabels).
  • Use it on projectionDetail fields and entityList/projectionList/ relatedList columns that would otherwise show bare option values.

Where it applies

Section titled “Where it applies”

Formats are declared where field display is configured (screen columns / detail fields / tables). The renderer (render-field, renderer DataTableCell) applies the spec; readOnly paths use the active app locale from the LocaleProvider.

Formatting does not validate, round, or convert the stored value. Put domain rules in the field definition or write handler.

See also

Section titled “See also”