---
source: https://carbone.io/documentation/design/formatters/date.html
title: "Date Formatting"
description: "List of functions to format your JSON dates"
generated_at: "2026-07-13"
---

# Date Formatting

List of functions to format your JSON dates  
COMMUNITY FEATURE Available for:  
✓ Carbone Cloud  
✓ Carbone On-premise  
✓ Embedded Carbone JS   v2.0+ 

## :formatD(patternOut, patternIn)

UPDATED v3.0.0+

Format dates.

It takes an output date pattern as an argument. Date patterns are available in [this section](#date-formats).  
It is possible to change the timezone through the option `options.timezone` and the lang through `options.lang`.  
List of timezones: [https://en.wikipedia.org/wiki/List\_of\_tz\_database\_time\_zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

| Params | Description | Type |
| --- | --- | --- |
| patternOut | output format | String |
| patternIn | input format, "ISO 8601" by default | String |

_Examples_

```javascript
// With API options: {
//   "lang": "en-us",
//   "timezone": "Europe/Paris"
// }
{d.value:formatD('L')} // input: "20160131" → output: "01/31/2016"
{d.value:formatD('LL')} // input: "20160131" → output: "January 31, 2016"
{d.value:formatD('LLLL')} // input: "20160131" → output: "Sunday, January 31, 2016 12:00 AM"
{d.value:formatD('dddd')} // input: "20160131" → output: "Sunday"
// With API options: {
//   "lang": "fr",
//   "timezone": "Europe/Paris"
// }
{d.value:formatD('LLLL')} // input: "2017-05-10T15:57:23.769561+03:00" → output: "mercredi 10 mai 2017 14:57"
{d.value:formatD('LLLL')} // input: "2017-05-10 15:57:23.769561+03:00" → output: "mercredi 10 mai 2017 14:57"
{d.value:formatD('LLLL')} // input: "20160131" → output: "dimanche 31 janvier 2016 00:00"
{d.value:formatD('dddd')} // input: "20160131" → output: "dimanche"
// With API options: {
//   "lang": "fr",
//   "timezone": "Europe/Paris"
// }
{d.value:formatD('dddd', 'YYYYMMDD')} // input: "20160131" → output: "dimanche"
{d.value:formatD('LLLL', 'X')} // input: 1410715640 → output: "dimanche 14 septembre 2014 19:27"
// With API options: {
//   "lang": "fr",
//   "timezone": "Asia/Singapore"
// }
{d.value:formatD('dddd', 'YYYYMMDD')} // input: "20160131" → output: "dimanche"
{d.value:formatD('LLLL', 'X')} // input: 1410715640 → output: "lundi 15 septembre 2014 01:27"
```

## :addD(amount, unit, patternIn)

v3.0.0+

Add a time to a date. Available units: day, week, month, quarter, year, hour, minute, second and millisecond.  
Units are case insensitive, and support plural and short forms.

| Params | Description | Type |
| --- | --- | --- |
| amount | The amount | Number |
| unit | The unit | String |
| patternIn | \[optional\] input format, ISO8601 by default | String |

_Examples_

```javascript
// With API options: {
//   "lang": "fr",
//   "timezone": "Europe/Paris"
// }
{d.value:addD('3', 'day')} // input: "2017-05-10T15:57:23.769561+03:00" → output: "2017-05-13T12:57:23.769Z"
{d.value:addD('3', 'month')} // input: "2017-05-10 15:57:23.769561+03:00" → output: "2017-08-10T12:57:23.769Z"
{d.value:addD('3', 'day')} // input: "20160131" → output: "2016-02-03T00:00:00.000Z"
{d.value:addD('3', 'month')} // input: "20160131" → output: "2016-04-30T00:00:00.000Z"
{d.value:addD('3', 'month', 'DD-YYYY-MM')} // input: "31-2016-01" → output: "2016-04-30T00:00:00.000Z"
```

## :subD(amount, unit, patternIn)

v3.0.0+

Subtract a time from a date. Available units: day, week, month, quarter, year, hour, minute, second and millisecond.  
Units are case insensitive, and support plural and short forms.

| Params | Description | Type |
| --- | --- | --- |
| amount | The amount | Number |
| unit | The unit | String |
| patternIn | \[optional\] input format, ISO8601 by default | String |

_Examples_

```javascript
// With API options: {
//   "lang": "fr",
//   "timezone": "Europe/Paris"
// }
{d.value:subD('3', 'day')} // input: "2017-05-10T15:57:23.769561+03:00" → output: "2017-05-07T12:57:23.769Z"
{d.value:subD('3', 'month')} // input: "2017-05-10 15:57:23.769561+03:00" → output: "2017-02-10T12:57:23.769Z"
{d.value:subD('3', 'day')} // input: "20160131" → output: "2016-01-28T00:00:00.000Z"
{d.value:subD('3', 'month')} // input: "20160131" → output: "2015-10-31T00:00:00.000Z"
{d.value:subD('3', 'month', 'DD-YYYY-MM')} // input: "31-2016-01" → output: "2015-10-31T00:00:00.000Z"
```

## :startOfD(unit, patternIn)

v3.0.0+

Create a date and set it to the start of a unit of time.

| Params | Description | Type |
| --- | --- | --- |
| unit | The unit | String |
| patternIn | \[optional\] input format, ISO8601 by default | String |

_Examples_

```javascript
// With API options: {
//   "lang": "fr",
//   "timezone": "Europe/Paris"
// }
{d.value:startOfD('day')} // input: "2017-05-10T15:57:23.769561+03:00" → output: "2017-05-10T00:00:00.000Z"
{d.value:startOfD('month')} // input: "2017-05-10 15:57:23.769561+03:00" → output: "2017-05-01T00:00:00.000Z"
{d.value:startOfD('day')} // input: "20160131" → output: "2016-01-31T00:00:00.000Z"
{d.value:startOfD('month')} // input: "20160131" → output: "2016-01-01T00:00:00.000Z"
{d.value:startOfD('month', 'DD-YYYY-MM')} // input: "31-2016-01" → output: "2016-01-01T00:00:00.000Z"
```

## :endOfD(unit, patternIn)

v3.0.0+

Create a date and set it to the end of a unit of time.

| Params | Description | Type |
| --- | --- | --- |
| unit | The unit | String |
| patternIn | \[optional\] input format, ISO8601 by default | String |

_Examples_

```javascript
// With API options: {
//   "lang": "fr",
//   "timezone": "Europe/Paris"
// }
{d.value:endOfD('day')} // input: "2017-05-10T15:57:23.769561+03:00" → output: "2017-05-10T23:59:59.999Z"
{d.value:endOfD('month')} // input: "2017-05-10 15:57:23.769561+03:00" → output: "2017-05-31T23:59:59.999Z"
{d.value:endOfD('day')} // input: "20160131" → output: "2016-01-31T23:59:59.999Z"
{d.value:endOfD('month')} // input: "20160131" → output: "2016-01-31T23:59:59.999Z"
{d.value:endOfD('month', 'DD-YYYY-MM')} // input: "31-2016-01" → output: "2016-01-31T23:59:59.999Z"
```

## :diffD(toDate, unit, patternFromDate, patternToDate)

v4.4.0+

Compute the difference between two dates and get an interval. List of available output units for the interval:

-   `day(s)` or `d` Day of Week (Sunday as 0, Saturday as 6)
-   `week(s)` or `w` Week of Year
-   `quarter(s)` or `Q` Quarter
-   `month(s)` or `M` Month (January as 0, December as 11)
-   `year(s)` or `y` Year
-   `hour(s)` or `h` Hour
-   `minute(s)` or `m` Minute
-   `second(s)` or `s` Second
-   `millisecond(s)` or `ms` Millisecond

| Params | Description | Type |
| --- | --- | --- |
| toDate | to date | String, Number |
| unit | The output unit: day, week, ... see the list above. Milliseconds by default. | String |
| patternFromDate | \[optional\] The pattern of `fromDate`, ISO8601 by default | String |
| patternToDate | \[optional\] The pattern of `toDate`, ISO8601 by default | String |

_Examples_

```javascript
{d.value:diffD('20101201')} // input: "20101001" → output: 5270400000
{d.value:diffD('20101201', 'second')} // input: "20101001" → output: 5270400
{d.value:diffD('20101201', 's')} // input: "20101001" → output: 5270400
{d.value:diffD('20101201', 'm')} // input: "20101001" → output: 87840
{d.value:diffD('20101201', 'h')} // input: "20101001" → output: 1464
{d.value:diffD('20101201', 'weeks')} // input: "20101001" → output: 8
{d.value:diffD('20101201', 'days')} // input: "20101001" → output: 61
{d.value:diffD('2010=12=01', 'ms', 'YYYY+MM+DD', 'YYYY=MM=DD')} // input: "2010+10+01" → output: 5270400000
```

## :convDate(patternIn, patternOut)

UNRECOMMENDED FOR USE v1.0.0+

Format dates

| Params | Description | Type |
| --- | --- | --- |
| patternIn | input format | String |
| patternOut | output format | String |

_Examples_

```javascript
// With API options: {
//   "lang": "en",
//   "timezone": "Europe/Paris"
// }
{d.value:convDate('YYYYMMDD', 'L')} // input: "20160131" → output: "01/31/2016"
{d.value:convDate('YYYYMMDD', 'LL')} // input: "20160131" → output: "January 31, 2016"
{d.value:convDate('YYYYMMDD', 'LLLL')} // input: "20160131" → output: "Sunday, January 31, 2016 12:00 AM"
{d.value:convDate('YYYYMMDD', 'dddd')} // input: "20160131" → output: "Sunday"
{d.value:convDate('X', 'LLLL')} // input: 1410715640 → output: "Sunday, September 14, 2014 7:27 PM"
// With API options: {
//   "lang": "fr",
//   "timezone": "Europe/Paris"
// }
{d.value:convDate('YYYYMMDD', 'LLLL')} // input: "20160131" → output: "dimanche 31 janvier 2016 00:00"
{d.value:convDate('YYYYMMDD', 'dddd')} // input: "20160131" → output: "dimanche"
```

Get inspired by one of our real-life examples: [Ticket](/examples/ticket/index.md), [E-Ticket](/examples/eticket/index.md) or [Prescription](/examples/prescription/index.md)

## Date formats

UPDATED v3.0.0+

| Format | Output | Description |
| --- | --- | --- |
| `X` | 1360013296 | Unix Timestamp |
| `x` | 1360013296123 | Unix Millisecond Timestamp |
| `YY` | 18 | Two-digit year |
| `YYYY` | 2018 | Four-digit year |
| `M` | 1-12 | The month, beginning at 1 |
| `MM` | 01-12 | The month, 2-digits |
| `MMM` | Jan-Dec | The abbreviated month name |
| `MMMM` | January-December | The full month name |
| `D` | 1-31 | The day of the month |
| `DD` | 01-31 | The day of the month, 2-digits |
| `d` | 0-6 | The day of the week, with Sunday as 0 |
| `dd` | Su-Sa | The minimal name of the day of the week |
| `ddd` | Sun-Sat | The short name of the day of the week |
| `dddd` | Sunday-Saturday | The name of the day of the week |
| `H` | 0-23 | The hour |
| `HH` | 00-23 | The hour, 2-digits |
| `h` | 1-12 | The hour, 12-hour clock |
| `hh` | 01-12 | The hour, 12-hour clock, 2-digits |
| `m` | 0-59 | The minute |
| `mm` | 00-59 | The minute, 2-digits |
| `s` | 0-59 | The second |
| `ss` | 00-59 | The second, 2-digits |
| `SSS` | 000-999 | The millisecond, 3-digits |
| `Z` | +05:00 | The offset from UTC, ±HH:mm |
| `ZZ` | +0500 | The offset from UTC, ±HHmm |
| `A` | AM PM |   |
| `a` | am pm |   |
| `Q` | 1-4 | Quarter |
| `Do` | 1st 2nd ... 31st | Day of Month with ordinal |
| `k` | 1-24 | The hour, beginning at 1 |
| `kk` | 01-24 | The hour, 2-digits, beginning at 1 |
| `w` | 1 2 ... 52 53 | Week of year |
| `ww` | 01 02 ... 52 53 | Week of year, 2-digits |
| `W` | 1 2 ... 52 53 | ISO Week of year |
| `WW` | 01 02 ... 52 53 | ISO Week of year, 2-digits |
| `wo` | 1st 2nd ... 52nd 53rd | Week of year with ordinal |
| `gggg` | 2017 | Week Year |
| `GGGG` | 2017 | ISO Week Year |
| `z` | EST | Abbreviated named offset |
| `zzz` | Eastern Standard Time | Unabbreviated named offset |

#### List of localized formats

Because preferred formatting differs based on language, there are a few tokens that can be used to format a date based on report language.

There are upper and lower case variations on the same formats. The lowercase version is intended to be the shortened version of its uppercase counterpart.

| Format | English Locale | Sample Output |
| --- | --- | --- |
| `LT` | h:mm A | 8:02 PM |
| `LTS` | h:mm:ss A | 8:02:18 PM |
| `L` | MM/DD/YYYY | 08/16/2018 |
| `LL` | MMMM D, YYYY | August 16, 2018 |
| `LLL` | MMMM D, YYYY h:mm A | August 16, 2018 8:02 PM |
| `LLLL` | dddd, MMMM D, YYYY h:mm A | Thursday, August 16, 2018 8:02 PM |
| `l` | M/D/YYYY | 8/16/2018 |
| `ll` | MMM D, YYYY | Aug 16, 2018 |
| `lll` | MMM D, YYYY h:mm A | Aug 16, 2018 8:02 PM |
| `llll` | ddd, MMM D, YYYY h:mm A | Thu, Aug 16, 2018 8:02 PM |

Source: [DayJS](https://day.js.org/docs/en/display/format)

## Current Date

The reserved keyword `{c.now}` returns the current date and time in UTC at the moment the document is generated.

If `now` is defined in [`complement`](/documentation/developer/http-api/generate-reports.md), that value will be used instead, allowing you to override the current date.

`{c.now}` can be chained with any [date formatter](/documentation/design/formatters/date.md), such as `:formatD`, to display the date in the format of your choice.

_Examples_

```cdata
{
}
```

```ctemplate
{c.now:formatD('YYYY-MM-DD')}{c.now:formatD('LL')}{c.now:formatD('LLLL')} 
```

```cresult
2025-10-17
October 17, 2025
Friday, October 17, 2025 10:00 AM
```

## Related topics

- [Text Formatting](/documentation/design/formatters/text.md)
- [How formatters work](/documentation/design/formatters/overview.md)
- [Number Formatting](/documentation/design/formatters/number.md)
- [Interval and Duration](/documentation/design/formatters/interval.md)
- [Currency Formatting](/documentation/design/formatters/currency.md)
- [Array manipulation](/documentation/design/formatters/array.md)