--- schema_version: "1" id: 0e192295b58266106369cc6fc3397d2cc0a5cf5af367bd71614f1f1181d74160 title: "Handlebars Helper Function: format" collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/handlebars/reference/utility/mcn-handlebars-reference-utility-format.md canonical_url: https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-utility-references/mcn-handlebars-reference-utility-format.html source_site: developer.salesforce.com content_type: documentation content_hash: 6d7453d3f131d5053fbdfdcfde36c3b9756895de124f2e910ccceecbe6d2c33c products: - Handlebars for Marketing Cloud Next - Marketing Cloud --- # Handlebars Helper Function: format Formats output based on a format string and optional type specification. It supports formatting dates, numbers, and strings according to specified patterns and culture settings. ## Availability This helper is available in the Winter ’26 release of Marketing Cloud Next. ## Syntax ```handlebars {{format subject formatString type culture}} ``` ## Parameters | Parameter | Type | Description | | -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subject` | Any | Required. The value to format. | | `formatString` | String | Required. The format pattern to apply. See [Format Strings](#format-strings). | | `type` | String | The type to format as. Valid values: `"date"`, `"numeric"`. If not specified, uses general string formatting. | | `culture` | String | The culture code for formatting, such as `en-US` or `zh_TW`. Supports both hyphen and underscore formats. Defaults to current runtime culture if not specified. | ## Format Strings The value that you specify for the `formatString` parameter determines the type of formatting to apply to the `subject`. These sections describe the different format strings that you can use. ### Date Format Strings Date formats are highly configurable and can be customized to suit your needs. These sections describe the different format strings that you can use. #### Preformatted Date and Time Strings Use the string patterns listed in this table to format dates and times. The values in the Example Output column are based on the date Monday, March 15, 2024 at 2:30:45 PM in the UTC-6 time zone with the `en_US` culture. | StringPattern | Name | Example Output | | ------------- | ---------------------- | --------------------------------- | | `d` | Short date | 3/15/2024 | | `D` | Long date | Friday, March 15, 2024 | | `f` | Full date/time (short) | Friday, March 15, 2024 2:30 PM | | `F` | Full date/time (long) | Friday, March 15, 2024 2:30:45 PM | | `g` | General (short) | 3/15/2024 2:30 PM | | `G` | General (long) | 3/15/2024 2:30:45 PM | | `M` | Month day | March 15 | | `O` | Round-trip | 2024-03-15T08:30:45.1230000-06:00 | | `R` | RFC1123 | Fri, 15 Mar 2024 14:30:45 GMT | | `s` | Sortable | 2024-03-15T08:30:45 | | `t` | Short time | 2:30 PM | | `T` | Long time | 2:30:45 PM | | `u` | Universal sortable | 2024-03-15 14:30:45Z | | `U` | Universal full | 2024-03-15T14:30:45.0Z | | `Y` | Year month | March 2024 | #### Date Components Use the string patterns listed in this table to format dates. The values in the Example column are based on the date Monday, March 15, 2024 at 2:30:45 PM in the UTC-6 time zone with the `en_US` culture. | String Pattern | Description | Example | Valid Range | | -------------- | -------------------------- | ------- | ----------------- | | `yyyy` | 4-digit year | 2024 | 0001–9999 | | `yyy` | 3-digit year (minimum) | 2024 | 001–999 | | `yy` | 2-digit year | 24 | 00–99 | | `y` | 1-digit year (minimum) | 2024 | 1–9999 | | `MMMM` | Full month name | March | Culture-dependent | | `MMM` | Abbreviated month name | Mar | Culture-dependent | | `MM` | 2-digit month | 03 | 01–12 | | `M` | Month without leading zero | 3 | 1–12 | | `dddd` | Full day of week | Friday | Culture-dependent | | `ddd` | Abbreviated day of week | Fri | Culture-dependent | | `dd` | 2-digit day | 15 | 01–31 | | `d` | Day without leading zero | 15 | 1–31 | #### Time Components Use the string patterns listed in this table to format times. The values in the Example column are based on the time 2:30:45 PM in the UTC-6 time zone with the `en_US` culture. | String Pattern | Description | Example | Valid Range | | -------------- | ---------------------------- | ------- | ----------------- | | `HH` | 24-hour format (2-digit) | 14 | 00–23 | | `H` | 24-hour format (1-digit min) | 14 | 0–23 | | `hh` | 12-hour format (2-digit) | 02 | 01–12 | | `h` | 12-hour format (1-digit min) | 2 | 1–12 | | `mm` | Minutes (2-digit) | 30 | 00–59 | | `m` | Minutes (1-digit min) | 30 | 0–59 | | `ss` | Seconds (2-digit) | 45 | 00–59 | | `s` | Seconds (1-digit min) | 45 | 0–59 | | `fff` | Milliseconds (3-digit) | 123 | 000–999 | | `ff` | Centiseconds (2-digit) | 12 | 00–99 | | `f` | Deciseconds (1-digit) | 1 | 0–9 | | `tt` | AM/PM designator | PM | Culture-dependent | | `t` | First char of AM/PM | P | Culture-dependent | #### Date Literals and Separators You can further format dates and times using these literals and separators. | String Pattern | Description | Example | | -------------- | ---------------------------- | ------- | | `'text'` | Literal text (single quotes) | 'of' | | `"text"` | Literal text (double quotes) | "the" | | `/` | Date separator | / | | `:` | Time separator | : | | `-` | Dash separator | - | | ` ` | Space | (space) | ### Numeric Format Strings You can customize the way that numbers are formatted by using predefined or custom format strings. #### Predefined Numeric Format Strings Use the string patterns listed in this table to format numbers. The values in the Example columns are based on the `en_US` culture setting. | Pattern | Name | Example (1234.567) | Example (-1234.567) | Notes | | ----------- | ------------------------- | ------------------ | ------------------- | -------------------------------------------------------------- | | `C` or `C2` | Currency | \$1,234.57 | (\$1,234.57) | Uses the specified culture's currency symbol and formatting. | | `C0` | Currency (no decimals) | \$1,235 | (\$1,235) | Rounds to nearest integer. | | `C4` | Currency (4 decimals) | \$1,234.5670 | (\$1,234.5670) | Zero-padded to 4 decimal places. | | `D` | Decimal | 1235 | -1235 | Rounds to nearest integer. | | `D8` | Decimal (8 digits) | 00001235 | -00001235 | Left-padded with zeros to 8 digits. | | `E` or `E2` | Scientific | 1.23E+003 | -1.23E+003 | Exponential notation with an uppercase 'E'. | | `e3` | Scientific (lowercase) | 1.235e+003 | -1.235e+003 | Exponential notation with a lowercase 'e'. | | `F` or `F2` | Fixed-point | 1234.57 | -1234.57 | Doesn’t include a thousands separator. | | `F0` | Fixed-point (no decimals) | 1235 | -1235 | Rounds to nearest integer. | | `F6` | Fixed-point (6 decimals) | 1234.567000 | -1234.567000 | Zero-padded to 6 decimal places. | | `G` | General | 1234.567 | -1234.567 | | | `N` or `N2` | Number | 1,234.57 | -1,234.57 | Includes a thousands separator based on the specified culture. | | `N0` | Number (no decimals) | 1,235 | -1,235 | Rounds to nearest integer. | | `P` or `P2` | Percent | 123,456.70% | -123,456.70% | | | `P0` | Percent (no decimals) | 123,457% | -123,457% | Rounds to nearest integer. | | `R` | Round-trip | 1234.567 | -1234.567 | Preserves precision. | | `X` | Hexadecimal | 4D2 | Error | Numbers A-F are shown in uppercase. | | `X8` | Hexadecimal (8 digits) | 000004D2 | Error | Numbers A-F are shown in uppercase. Zero-padded to 8 digits. | | `x` | Hexadecimal (lowercase) | 4d2 | Error | Numbers A-F are shown in lowercase. | #### Custom Numeric Format Strings When you specify a custom numeric format string, use either `#` or `0` as a placeholder for the digits in the number. Use the custom format strings listed in this table to format numbers. The values in the Example columns are based on the `en_US` culture setting. | Pattern | Description | Example (1234.567) | Example (0.567) | | --------------------------------------------- | ------------------- | ------------------ | --------------- | | `.` | Decimal point | 1234.567 | 0.567 | | `,` | Thousands separator | 1,234.567 | 0.567 | | `%` | Percentage | 123456.7% | 56.7% | | `‰` | Per mille | 1234567‰ | 567‰ | | `E0` | Scientific notation | 1.234567E3 | 5.67E-1 | | `` | Literal string | 1234.567 units | 0.567 units | | `\` | Escape character | 1234.567\% | 0.567\% | To specify separate formats for positive, negative, and zero values, use the `;` character. For example, `{{format 1234.567, "N2;N0;N2"}}` returns `1,234.57`, and `{{format -1234.567, "N2;(F2);N0"}}` returns `(1,234.57)`. This table includes examples of custom numeric formatting strings. | Format String | Input | Output | Description | | ------------------ | -------- | --------- | ------------------------------- | | `#,##0.00` | 1234.567 | 1,234.57 | Standard number with 2 decimals | | `#,##0` | 1234.567 | 1,235 | Rounded to whole number | | `000000` | 123 | 000123 | Zero-padded to 6 digits | | `###.###` | 123.456 | 123.456 | Optional digits | | `#.##;(#.##);Zero` | -123.45 | (123.45) | Negative format section | | `#.##;(#.##);Zero` | 0 | Zero | Zero format section | | `# 'units'` | 123 | 123 units | Literal text | | `#.##%` | 0.1234 | 12.34% | Percentage | | `#.##‰` | 0.1234 | 123.4‰ | Per mille | ### String Formatting When the `type` parameter is omitted or is set to `string`, these rules apply: - If the `formatString` parameter is empty, the string is returned as-is. - If any format string value is provided, the value is treated as a string template placeholder. - If formatting fails, an exception is thrown. These rules are applied when formatting strings: 1. All format patterns are case-sensitive. 2. Literal text must be enclosed in single or double quotes. 3. Use a backslash (`\`) to escape special characters. 4. If a pattern isn’t valid, an exception is thrown. 5. Date patterns work only with date types, and numeric patterns workonly with numbers. 6. Some patterns, such as day and month names, vary by culture. 7. Numbers can have up to 15 significant digits. 8. Use semicolon (`;`) to separate positive, negative, and zero formats. ### Culture and Locale Specification Use the `culture` parameter to specify the culture to use for formatting. These locale codes are supported: - `en-US` (English - United States) - `en-GB` (English - United Kingdom) - `fr-FR` (French - France) - `de-DE` (German - Germany) - `es-ES` (Spanish - Spain) - `ja-JP` (Japanese - Japan) - `zh-CN` (Chinese - China) - `zh-TW` (Chinese - Taiwan) The `culture` value determines the date format conventions, currency symbols, decimal separators, thousands separators, day names, and month names that are used for formatting. ## Return Value The function returns the formatted value as a string. If formatting fails, it returns the original value as a string (backward compatibility). All format strings are case-sensitive. ## See Also - [FormatCurrency](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-utility-references/mcn-handlebars-reference-utility-formatcurrency.md) - [FormatNumber](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-utility-references/mcn-handlebars-reference-utility-formatnumber.md)