---
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-06-08
---
# 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:
| \# | 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
```docmosis
**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**
| ***value*** | ***format*** | ***result*** |
| --- | --- | --- |
| WHOLE NUMBERS \- No thousands separator. No decimal places. | | |
| --- | --- | --- |
| 12345 12,345 123\.45 12345\.612,345\.67 | \#\#\#\#\# | \<\<{numFormat( 12345, ‘\#’ )}\>\>\<\<{numFormat( ‘12,345’, ‘\#’ )}\>\>\<\<{numFormat( 123\.45, ‘\#’ )}\>\>\<\<{numFormat( 12345\.6, ‘\#’ )}\>\>\<\<{numFormat( ‘12,345\.67’, ‘\#’ )}\>\> |
| THOUSANDS \- Comma separated thousands. No decimal places. | | |
| --- | --- | --- |
| 123456 123456\.7 1234567\.89 | \#,\#\#\#\#,\#\#\#\#,\#\#\# | \<\<{numFormat( 123456, ‘\#,\#\#\#’ )}\>\>\<\<{numFormat( 123456\.7, ‘\#,\#\#\#’ )}\>\>\<\<{numFormat( 1234567\.89, ‘\#,\#\#\#’ )}\>\> |
| CURRENCY \- Leading $ sign. Comma separated thousands. Two decimal places. | | |
| --- | --- | --- |
| 12 123\.4 123\.4567 1234 123456789 123456\.789 | $\#,\#\#\#.00$\#,\#\#\#.00$\#,\#\#\#.00$\#,\#\#\#.00$\#,\#\#\#.00$\#,\#\#\#.00 | \<\<{numFormat( 12, ‘$\#,\#\#\#.00’ )}\>\>\<\<{numFormat( 123\.4, ‘$\#,\#\#\#.00’ )}\>\>\<\<{numFormat( 123\.4567, ‘$\#,\#\#\#.00’ )}\>\>\<\<{numFormat( 1234, ‘$\#,\#\#\#.00’ )}\>\>\<\<{numFormat( 123456789, ‘$\#,\#\#\#.00’ )}\>\>\<\<{numFormat( 123456\.789, ‘$\#,\#\#\#.00’ )}\>\> |
**Decimals and Accuracy**
| ***value*** | ***format*** | ***result*** |
| --- | --- | --- |
| Always show three decimal places. (Add/remove zeroes for more/less places) | | |
| --- | --- | --- |
| 123 123\.4 123\.45678 1234567\.8 | \#.000\#.000\#.000\#.000 | \<\<{numFormat( 123, ‘\#.000’ )}\>\>\<\<{numFormat( 123\.4, ‘\#.000’ )}\>\>\<\<{numFormat( 123\.45678, ‘\#.000’ )}\>\>\<\<{numFormat( 1234567\.8, ‘\#.000’ )}\>\> |
| None or one decimal place. (Add/remove \#’s after the point for more/less places) | | |
| --- | --- | --- |
| 123123\.4 123\.4567 | \#.\#\#.\#\#.\# | \<\<{numFormat( 123, ‘\#.\#’ )}\>\>\<\<{numFormat( 123\.4, ‘\#.\#’ )}\>\>\<\<{numFormat( 123\.4567, ‘\#.\#’ )}\>\> |
| Always show a minimum of four digits. (Add/remove zeroes for more/less places) | | |
| --- | --- | --- |
| 12123456123\.456 | 000000000000 | \<\<{numFormat( 12, ‘0000’ )}\>\>\<\<{numFormat( 123456, ‘0000’ )}\>\>\<\<{numFormat( 123\.456, ‘0000’ )}\>\> |
**Units**
| Apply units of measurement after a number. | | |
| --- | --- | --- |
| 123\.4 123 123456 | \#.00 kg\# miles\#,\#\#\# feet | \<\<{numFormat( 123\.45, ‘\#.00 kg’ )}\>\>\<\<{numFormat( 123, ‘\# miles’ )}\>\>\<\<{numFormat( 123456, ‘\#,\#\#\# feet’ )}\>\> |
**Percentages**
| Percentage | | |
| --- | --- | --- |
| 0\.31\.10\.120\.12340\.50\.1234 | \#%\#%\#.00%\#.00%%\#%\#.00 | \<\<{numFormat( 0\.3, ‘\#%’ )}\>\>\<\<{numFormat( 1\.1, ‘\#%’ )}\>\>\<\<{numFormat( 0\.12, ‘\#.00%’ )}\>\>\<\<{numFormat( 0\.1234, ‘\#.00%’ )}\>\>\<\<{numFormat( 0\.5, ‘%\#’ )}\>\>\<\<{numFormat( 0\.1234, ‘%\#.0’ )}\>\> |
**Formatting input Data**
| Perform calculations on input data and format the result. | |
| --- | --- |
| weight \= \<\\>units \= \<\\>distance \= \<\\>price \= \<\\>qty \= \<\\>testScore \= \<\\>testTotal \= \<\\> | \<\<{numFormat(weight,’\# ’\+units)}\>\>\<\<{numFormat(distance/1000, ‘\#.\# km’)}\>\>\<\<{numFormat(price\*qty, ‘$\#,\#\#\#.00’)}\>\>\<\<{numFormat(testScore/testTotal, ‘\# %’)}\>\> |
**Same Number : Different Formats**
| ***value*** | ***format*** | ***result*** |
| --- | --- | --- |
| 1234567\.8911234567\.8911234567\.8911234567\.8911234567\.8911234567\.8911234567\.8911234567\.8911234567\.8911234567\.8911234567\.891 | \#,\#\#\#\#,\#\#\#\#.\#,\#\#\#.\#\#.\#\#\#\#\#\#.0\#.00000$\#,\#\#\#.00abc \#\# abc | \<\<{numFormat( 1234567\.891, ‘\#’ )}\>\>\<\<{numFormat( 1234567\.891, ‘,\#\#\#’ )}\>\>\<\<{numFormat( 1234567\.891, ‘\#,\#\#\#’ )}\>\>\<\<{numFormat( 1234567\.891, ‘\#.\#’ )}\>\>\<\<{numFormat( 1234567\.891, ‘,\#\#\#.\#’ )}\>\>\<\<{numFormat( 1234567\.891, ‘\#.\#\#\#\#\#’ )}\>\>\<\<{numFormat( 1234567\.891, ‘\#.0’ )}\>\>\<\<{numFormat( 1234567\.891, ‘\#.0000’ )}\>\>\<\<{numFormat(1234567\.891, ‘$\#,\#\#\#.00’ )}\>\>\<\<{numFormat( 1234567\.891, ‘abc \#’ )}\>\>\<\<{numFormat( 1234567\.891, ‘\# abc’ )}\>\> |
| --- | --- | --- |
```