Formatting

CxJS provides built-in support for formatting numbers, dates, and currencies. Formats can be applied to widgets via the format property or programmatically using Format.value().

Using Formats

Widgets like NumberField and DateField accept a format property that controls how values are displayed:

<div class="flex flex-col gap-4">
  <LabelsTopLayout columns={2}>
    <NumberField
      value={bind(m.price, 100)}
      label="Price"
      format="currency;USD;2"
    />
    <NumberField value={bind(m.quantity, 5)} label="Quantity" format="n;0" />
    <DateField
      value={bind(m.date, new Date())}
      label="Date"
      format="d;yyyyMMdd"
    />
  </LabelsTopLayout>
  <table class="w-full text-sm mt-4">
    <thead>
      <tr>
        <th class="text-left py-2 pr-4 border-b border-border">Format</th>
        <th class="text-left py-2 border-b border-border">Result</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="py-2 pr-4">
          <code>currency;USD;2</code>
        </td>
        <td class="py-2" text={format(m.price, "currency;USD;2")} />
      </tr>
      <tr>
        <td class="py-2 pr-4">
          <code>n;0</code>
        </td>
        <td class="py-2" text={format(m.quantity, "n;0")} />
      </tr>
      <tr>
        <td class="py-2 pr-4">
          <code>d;yyMd</code>
        </td>
        <td class="py-2" text={format(m.date, "d;yyMd")} />
      </tr>
      <tr>
        <td class="py-2 pr-4">
          <code>d;DDDDyyyyMMMMd</code>
        </td>
        <td
          class="py-2"
          text={expr(m.date, (date) => Format.value(date, "d;DDDDyyyyMMMMd"))}
        />
      </tr>
    </tbody>
  </table>
</div>

interface PageModel {
  price: number;
  quantity: number;
  date: Date;
}

const m = createModel<PageModel>();

import { createModel } from "cx/data";
import { Format } from "cx/util";
import { bind, expr, format, LabelsTopLayout } from "cx/ui";
import { NumberField, DateField } from "cx/widgets";

For formatting bound values in text, see the Formatting Values section in Data Binding.

Culture-Sensitive Formatting

Date, currency, and number formats depend on culture settings. Enable culture-sensitive formatting before use:

import { enableCultureSensitiveFormatting } from "cx/ui";

enableCultureSensitiveFormatting();

This ensures formats respect locale-specific conventions for decimal separators, date order, currency symbols, and month/day names.

Format Syntax

Format strings use semicolons to separate parameters:

formatType;param1;param2

Use a pipe | to specify text for null values:

n;2|N/A

Chain multiple formats with colons (applied left-to-right):

n;2:suffix; USD

Number Formats

Number formats support min and max decimal places, plus optional flags: n;minDecimals;maxDecimals;flags. If only one decimal value is provided, it’s used for both min and max.

Currency Format

The currency format supports an optional currency code, decimal places, and flags: currency;code;minDecimals;maxDecimals;flags. The currency code can be omitted to use the default currency.

Format Flags

These flags can be added to number and currency formats:

Flags can be combined, e.g., +ac for all three options. The default currency is determined by culture settings.

String Formats

String formats allow adding prefixes, suffixes, and wrapping values:

These can be chained with other formats:

Format.value(5, "n;2:wrap;(;)"); // "(5.00)"
Format.value(180, "n;0:suffix; cm"); // "180 cm"

Date Formats

Date formats use pattern codes concatenated together. Separators are provided by the culture settings, not the pattern.

Date Pattern Characters

Pattern codes are concatenated without separators. Four characters means full name, three is abbreviated, two is padded, one is numeric.

Time Pattern Characters

Date and time patterns can be combined: d;yyyyMMddHHmm formats both date and time. Add N for 24-hour format: d;yyyyMMddNHHmm.

For more details on culture-sensitive formatting, see intl-io.

Programmatic Formatting

Use Format.value() to format values in code:

import { Format } from "cx/util";

Format.value(1234.5, "n;2"); // "1,234.50"
Format.value(0.15, "p;0"); // "15%"
Format.value(new Date(), "d;yyyyMMdd"); // "02/01/2024"

Use the format helper to format bound values:

import { format } from "cx/ui";

<span text={format(m.price, "currency;USD")} />;

Alternatively, use expr with Format.value for more control:

import { expr } from "cx/ui";
import { Format } from "cx/util";

<span text={expr(m.price, (price) => Format.value(price, "currency;USD"))} />;

String Templates

Use StringTemplate.format when you need to combine multiple values into a single formatted string:

import { StringTemplate } from "cx/util";

// Positional arguments
StringTemplate.format(
  "{0} bought {1} items for {2:currency;USD}",
  "John",
  5,
  49.99,
);
// "John bought 5 items for $49.99"

// Named properties with an object
StringTemplate.format("{name} - {date:d;yyyyMMdd}", {
  name: "Report",
  date: new Date(),
});
// "Report - 02/01/2024"

Use StringTemplate.compile to create a reusable formatter function:

const formatter = StringTemplate.compile("{name}: {value:currency;USD}");
formatter({ name: "Total", value: 99.99 }); // "Total: $99.99"
formatter({ name: "Tax", value: 7.5 }); // "Tax: $7.50"

Custom Formats

Register custom formats using Format.register:

import { Format } from "cx/util";

// Simple format
Format.register("brackets", (value) => `(${value})`);

// Use it
Format.value("test", "brackets"); // "(test)"

For formats with parameters, use Format.registerFactory:

Format.registerFactory("suffix", (format, suffix) => {
  return (value) => value + suffix;
});

// Use it
Format.value(100, "suffix; kg"); // "100 kg"