---
title: "Formatting numbers"
description: "Format numbers in templates to display customised decimals, thousands separators, currency symbols, units, and percentages in generated documents."
canonical_url: "https://resources.docmosis.com/template-tutorials/format-numbers"
last_reviewed: 2026-09-03
---

# Formatting numbers

Docmosis allows you to control how numbers are displayed in the finished document.
For example: the raw data may have numbers like: 1234.5.
Using the built-in function numFormat the number can be formatted so that it looks like this: $1,234.50.

## Examples

It is best to view the TEMPLATE and OUTPUT files side-by-side to understand the formatting that has been applied.

## The numFormat function

The numFormat function requires two parameters, value and format, as shown in the syntax:
numFormat ( value, format )
The first is the value to be formatted and the second is a format string that describes the format to be applied.
The value can be taken directly from the data or the result of a calculation. 
The format string should be enclosed in single quotes, as in this example: '$#,###.00'.

### Constructing the format string

The format string can contain:

| Character | Description |
| --- | --- |
| # | Hash represents any digit. If the # appears on the right of the decimal then a digit will only be shown if it is not zero. So trailing zeroes are not shown. |
| 0 | Zero represents any digit.  A digit will always be shown.  The result will be padded with leading or trailing zeroes as needed. |
| . | If a decimal point is present in the format string then the desired number of digits after the decimal point can be described using a # or 0. The number of digits before the point will expand to match the value being formatted. |
| , | This is commonly used as the thousands separator. If a , (comma) appears in the format string, then the number of digits between the , (comma) and the . (decimal point) will be repeated in blocks. Most common is 3 digits. |
| % | If a percent character appears in the format then the value will be interpreted as a percentage, i.e. the value will be multiplied by 100, then the format will be applied to the result. |
| other characters | Any other characters at that start or finish of the format string will also appear in the formatted result.  This is useful for adding currency symbols such as $ (dollar) ,£ (pounds) , etc. at the start of a number for prices/totals/monetary amounts or adding units of measurement at the end of a number for weight/distance/etc. |

### Other formatting options

Please read the Template Guide for the full list of formatting options including displaying numbers/money using the conventions from different geographic locales.

## Formatting numbers - related json data

```json
{
"weight": "1234",
"units": "kg",
"distance": "5523",
"price": "1.2",
"qty": "150",
"testScore": "30",
"testTotal": "40"
}
```

## Formatting numbers - example template syntax

### Formatting Numbers

Docmosis has a built-in function to format numbers:
***numFormat ( value, format )***
The input parameters are:
***value*** *= the number to format*
***format*** *= a string that represents the format to apply*
***numFormat*** will round the ***value*** to the required accuracy as indicated by the ***format***.
The ***format*** string should be enclosed in single quotes.

#### Common Formats

**WHOLE NUMBERS** - No thousands separator. No decimal places.



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 12345 | # | <<{numFormat( 12345, ‘#’ )}>> | 12345 |
| 12,345 | # | <<{numFormat( ‘12,345’, ‘#’ )}>> | 12345 |
| 123.45 | # | <<{numFormat( 123.45, ‘#’ )}>> | 123 |
| 12345.6 | # | <<{numFormat( 12345.6, ‘#’ )}>> | 12346 |
| 12,345.67 | # | <<{numFormat( ‘12,345.67’, ‘#’ )}>> | 12346 |




**THOUSANDS** - Comma separated thousands. No decimal places.



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 123456 | #,### | <<{numFormat( 123456, ‘#,###’ )}>> | 123,456 |
| 123456.7 | #,### | <<{numFormat( 123456.7, ‘#,###’ )}>> | 123,457 |
| 1234567.89 | #,### | <<{numFormat( 1234567.89, ‘#,###’ )}>> | 1,234,568 |

**CURRENCY** - Leading $ sign. Comma separated thousands. Two decimal places.



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 12 | $#,###.00 | <<{numFormat( 12, ‘$#,###.00’ )}>> | $12.00 |
| 123.4 | $#,###.00 | <<{numFormat( 123.4, ‘$#,###.00’ )}>> | $123.40 |
| 123.4567 | $#,###.00 | <<{numFormat( 123.4567, ‘$#,###.00’ )}>> | $123.46 |
| 1234 | $#,###.00 | <<{numFormat( 1234, ‘$#,###.00’ )}>> | $1,234.00 |
| 123456789 | $#,###.00 | <<{numFormat( 123456789, ‘$#,###.00’ )}>> | $123,456,789.00 |
| 123456.789 | $#,###.00 | <<{numFormat( 123456.789, ‘$#,###.00’ )}>> | $123,456.79 |


#### Decimals and Accuracy

**Always show three decimal places**. (Add/remove zeroes for more/less places)



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 123 | #.000 | <<{numFormat( 123, ‘#.000’ )}>> | 123.000 |
| 123.4 | #.000 | <<{numFormat( 123.4, ‘#.000’ )}>> | 123.400 |
| 123.45678 | #.000 | <<{numFormat( 123.45678, ‘#.000’ )}>> | 123.457 |
| 1234567.8 | #.000 | <<{numFormat( 1234567.8, ‘#.000’ )}>> | 1234567.800 |

**None or one decimal place**. (Add/remove #’s after the point for more/less places)



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 123 | #.# | <<{numFormat( 123, ‘#.#’ )}>> | 123 |
| 123.4 | #.# | <<{numFormat( 123.4, ‘#.#’ )}>> | 123.4 |
| 123.4567 | #.# | <<{numFormat( 123.4567, ‘#.#’ )}>> | 123.5 |

**Always show a minimum of four digits**. (Add/remove zeroes for more/less places)



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 12 | 0000 | <<{numFormat( 12, ‘0000’ )}>> | 0012 |
| 123456 | 0000 | <<{numFormat( 123456, ‘0000’ )}>> | 123456 |
| 123.456 | 0000 | <<{numFormat( 123.456, ‘0000’ )}>> | 0123 |



#### Percentages



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 0.3 | #% | <<{numFormat( 0.3, ‘#%’ )}>> | 30% |
| 1.1 | #% | <<{numFormat( 1.1, ‘#%’ )}>> | 110% |
| 0.12 | #.00% | <<{numFormat( 0.12, ‘#.00%’ )}>> | 12.00% |
| 0.1234 | #.00% | <<{numFormat( 0.1234, ‘#.00%’ )}>> | 12.34% |
| 0.5 | %# | <<{numFormat( 0.5, ‘%#’ )}>> | %50 |
| 0.1234 | %#.0 | <<{numFormat( 0.1234, ‘%#.0’ )}>> | %12.3 |



#### Units

Apply units of measurement after a number.



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 123.45 | #.00 kg | <<{numFormat( 123.45, ‘#.00 kg’ )}>> | 123.45 kg |
| 123 | # miles | <<{numFormat( 123, ‘# miles’ )}>> | 123 miles |
| 123456 | #,### feet | <<{numFormat( 123456, ‘#,### feet’ )}>> | 123,456 feet |



#### Formatting Calculations

Perform calculations on input data and format the result.



| ***input data*** | ***field*** | ***result*** |
| --- | --- | --- |
| weight = <<weight>> units = <<units>> | <<{numFormat(weight,’# ’+units)}>> | 1234 kg |
| distance = <<distance>> | <<{numFormat(distance/1000, ‘#.# km’)}>> | 5.5 km |
| price = <<price>> qty = <<qty>> | <<{numFormat(price*qty, ‘$#,###.00’)}>> | $180.00 |
| testScore = <<testScore>> testTotal = <<testTotal>> | <<{numFormat(testScore/testTotal, ‘# %’)}>> | 75 % |




#### Same Number : Many Different Formats



| ***value*** | ***format*** | ***field*** | ***result*** |
| --- | --- | --- | --- |
| 1234567.891 | # | <<{numFormat( 1234567.891, ‘#’ )}>> | 1234568 |
| 1234567.891 | ,### | <<{numFormat( 1234567.891, ‘,###’ )}>> | 1,234,568 |
| 1234567.891 | #,### | <<{numFormat( 1234567.891, ‘#,###’ )}>> | 1,234,568 |
| | | | |
| 1234567.891 | #.# | <<{numFormat( 1234567.891, ‘#.#’ )}>> | 1234567.9 |
| 1234567.891 | ,###.# | <<{numFormat( 1234567.891, ‘,###.#’ )}>> | 1,234,567.9 |
| 1234567.891 | #.##### | <<{numFormat( 1234567.891, ‘#.#####’ )}>> | 1234567.891 |
| | | | |
| 1234567.891 | #.0 | <<{numFormat( 1234567.891, ‘#.0’ )}>> | 1234567.9 |
| 1234567.891 | #.0000 | <<{numFormat( 1234567.891, ‘#.0000’ )}>> | 1234567.8910 |
| 1234567.891 | $#,###.00 | <<{numFormat(1234567.891, ‘$#,###.00’ )}>> | $1,234,567.89 |
| | | | |
| 1234567.891 | abc # | <<{numFormat( 1234567.891, ‘abc #’ )}>> | abc 1234568 |
| 1234567.891 | # abc | <<{numFormat( 1234567.891, ‘# abc’ )}>> | 1234568 abc |