---
source: https://carbone.io/documentation/design/formatters/text.html
title: "Text Formatting"
description: "List of functions to manipulate and transform your JSON strings"
generated_at: "2026-07-08"
---

# Text Formatting

List of functions to manipulate and transform your JSON strings  
COMMUNITY FEATURE Available for:  
✓ Carbone Cloud  
✓ Carbone On-premise  
✓ Embedded Carbone JS   v2.0+ 

## :lowerCase

v0.12.5+

Lower case all letters

_Examples_

```javascript
{d.value:lowerCase()} // input: "My Car" → output: "my car"
{d.value:lowerCase()} // input: "my car" → output: "my car"
{d.value:lowerCase()} // input: null → output: null
{d.value:lowerCase()} // input: 1203 → output: 1203
```

## :upperCase

v0.12.5+

Upper case all letters

_Examples_

```javascript
{d.value:upperCase()} // input: "My Car" → output: "MY CAR"
{d.value:upperCase()} // input: "my car" → output: "MY CAR"
{d.value:upperCase()} // input: null → output: null
{d.value:upperCase()} // input: 1203 → output: 1203
```

## :ucFirst

v0.12.5+

Upper case first letter

_Examples_

```javascript
{d.value:ucFirst()} // input: "My Car" → output: "My Car"
{d.value:ucFirst()} // input: "my car" → output: "My car"
{d.value:ucFirst()} // input: null → output: null
{d.value:ucFirst()} // input: undefined → output: undefined
{d.value:ucFirst()} // input: 1203 → output: 1203
```

## :ucWords

v0.12.5+

Upper case the first letter of all words

_Examples_

```javascript
{d.value:ucWords()} // input: "my car" → output: "My Car"
{d.value:ucWords()} // input: "My cAR" → output: "My CAR"
{d.value:ucWords()} // input: null → output: null
{d.value:ucWords()} // input: undefined → output: undefined
{d.value:ucWords()} // input: 1203 → output: 1203
```

## :print(message)

v0.13.0+

Always return the same message if called (sort of "catch all" formatter)

| Params | Description | Type |
| --- | --- | --- |
| message | text to print | String |

_Examples_

```javascript
{d.value:print('hello!')} // input: "My Car" → output: "hello!"
{d.value:print('hello!')} // input: "my car" → output: "hello!"
{d.value:print('hello!')} // input: null → output: "hello!"
{d.value:print('hello!')} // input: 1203 → output: "hello!"
```

## :printJSON

v4.23.0+

Stringify the object/array

_Examples_

```javascript
{d.value:printJSON()} // input: [{"id":2,"name":"homer"},{"id":3,"name":"bart"}] → output: "[\n  {\"id\": 2, \"name\": \"homer\"},\n  {\"id\": 3, \"name\": \"bart\"}\n]"
{d.value:printJSON()} // input: "my car" → output: "\"my car\""
```

## :unaccent

v1.1.0+

Removes accents from text

_Examples_

```javascript
{d.value:unaccent()} // input: "crème brulée" → output: "creme brulee"
{d.value:unaccent()} // input: "CRÈME BRULÉE" → output: "CREME BRULEE"
{d.value:unaccent()} // input: "être" → output: "etre"
{d.value:unaccent()} // input: "éùïêèà" → output: "euieea"
```

## :convCRLF

v4.1.0+

It renders carriage return `\r\n` and line feed `\n` into documents instead of printing them as a string.  
Importante notes:

-   Feature supported for DOCX, PPTX, ODT, ODP, and ODS files.
-   ODS supports is experimental for now, contact the support if you find issues.
-   Since `v3.5.3`, using the `:convCRLF` formatter before `:html` converts `\n` to `<br>` tags. Usage example: `{d.content:convCRLF:html}`

_Examples_

```javascript
// With API options: {
//   "extension": "odt"
// }
{d.value:convCRLF()} // input: "my blue \n car" → output: "my blue <text:line-break/> car"
{d.value:convCRLF()} // input: "my blue \r\n car" → output: "my blue <text:line-break/> car"
// With API options: {
//   "extension": "docx"
// }
{d.value:convCRLF()} // input: "my blue \n car" → output: "my blue </w:t><w:br/><w:t xml:space=\"preserve\"> car"
{d.value:convCRLF()} // input: "my blue \r\n car" → output: "my blue </w:t><w:br/><w:t xml:space=\"preserve\"> car"
```

## :substr(begin, end, wordMode)

NEW v4.18.0+

Slice a string with a begin and an end.

| Params | Description | Type |
| --- | --- | --- |
| begin | Zero-based Index at which to begin extraction. | Integer |
| end | \[optional\] Zero-based index before which to end extraction | Integer |
| wordMode | \[optional\] If `true`, it never cuts words. In such a case:   \- `end` must be greater than `begin` and negative values cannot be used. `end - begin` = maximum number of characters per line of text   \- A word can only be truncated only if it does not fit in the line.   In this case, the word always starts at the beginning of a new line, just like in Word or LibreOffice   \- The same line width (end - begin) must be used between successive calls of `substr` to print all the words of the text (no gaps). Ex:   `{d.text(0 , 50 , true)}` -> line 1 of 50 characters   `{d.text(50 , 100, true)}` -> line 2 of 50 characters   `{d.text(100, 150, true)}` -> line 3 of 50 characters   `{d.text(150, 200, last)}` -> line 4 of infinite characters   \- `last` can be used instead of `true` to print the rest of the text, even if it is longer than the defined line width | Mixed |

_Examples_

```javascript
{d.value:substr(0, 3)} // input: "foobar" → output: "foo"
{d.value:substr(1)} // input: "foobar" → output: "oobar"
{d.value:substr(-2)} // input: "foobar" → output: "ar"
{d.value:substr(2, -1)} // input: "foobar" → output: "oba"
{d.value:substr(0, 11, true)} // input: "abcd efg hijklm" → output: "abcd efg "
{d.value:substr(1, 11, true)} // input: "abcd efg hijklm" → output: "abcd efg "
```

## :split(delimiter)

NEW v4.12.0+

Split a string using a delimiter

It can be used with `arrayJoin('', 1, 2)` to select one specific item of the generated array

| Params | Description | Type |
| --- | --- | --- |
| delimiter | The delimiter | String |

_Examples_

```javascript
{d.value:split('c')} // input: "abcdefc12" → output: ["ab","def","12"]
{d.value:split('.')} // input: 1222.1 → output: ["1222","1"]
{d.value:split('/')} // input: "ab/cd/ef" → output: ["ab","cd","ef"]
```

## :padl(targetLength, padString)

NEW v3.0.0+

Pad the string from the start with another string

| Params | Description | Type |
| --- | --- | --- |
| targetLength | The length of the resulting string once the string has been padded. If the value is less than string length, then string is returned as-is. | number |
| padString | The string to pad the current str with. If padString is too long to stay within the targetLength, it will be truncated from the end. The default value is " " | String |

_Examples_

```javascript
{d.value:padl(10)} // input: "abc" → output: "       abc"
{d.value:padl(10, 'foo')} // input: "abc" → output: "foofoofabc"
{d.value:padl(6, '123465')} // input: "abc" → output: "123abc"
{d.value:padl(8, '0')} // input: "abc" → output: "00000abc"
{d.value:padl(1)} // input: "abc" → output: "abc"
```

## :padr(targetLength, padString)

NEW v3.0.0+

Pad the string from the end with another string

| Params | Description | Type |
| --- | --- | --- |
| targetLength | The length of the resulting string once the string has been padded. If the value is less than string length, then string is returned as-is. | number |
| padString | The string to pad the current str with. If padString is too long to stay within the targetLength, it will be truncated from the end. The default value is " " | String |

_Examples_

```javascript
{d.value:padr(10)} // input: "abc" → output: "abc       "
{d.value:padr(10, 'foo')} // input: "abc" → output: "abcfoofoof"
{d.value:padr(6, '123465')} // input: "abc" → output: "abc123"
{d.value:padr(8, '0')} // input: "abc" → output: "abc00000"
{d.value:padr(1)} // input: "abc" → output: "abc"
```

## :ellipsis(maximum)

NEW v4.12.0+

Add "..." if the text is too long

| Params | Description | Type |
| --- | --- | --- |
| maximum | number of characters to print. | Integer |

_Examples_

```javascript
{d.value:ellipsis(3)} // input: "abcdef" → output: "abc..."
{d.value:ellipsis(6)} // input: "abcdef" → output: "abcdef"
{d.value:ellipsis(10)} // input: "abcdef" → output: "abcdef"
```

## :prepend(textToPrepend)

NEW v4.12.0+

add a prefix to a text

| Params | Description | Type |
| --- | --- | --- |
| textToPrepend | text to prepend | string |

_Examples_

```javascript
{d.value:prepend('123')} // input: "abcdef" → output: "123abcdef"
```

## :append(textToAppend)

NEW v4.12.0+

Add a suffix to a text

| Params | Description | Type |
| --- | --- | --- |
| textToAppend | text to append | string |

_Examples_

```javascript
{d.value:append('123')} // input: "abcdef" → output: "abcdef123"
```

## :replace(oldText, newText)

NEW v4.12.0+

Replace a text based on a pattern

All matches of the pattern (first argument: `oldText`) is replaced by the replacement string (second argument: `newText`).  
The pattern can only be a string.

| Params | Description | Type |
| --- | --- | --- |
| oldText | old text to replace | string |
| newText | new text | string |

_Examples_

```javascript
{d.value:replace('cd', 'OK')} // input: "abcdef abcde" → output: "abOKef abOKe"
{d.value:replace('cd')} // input: "abcdef abcde" → output: "abef abe"
{d.value:replace('cd', null)} // input: "abcdef abcde" → output: "abef abe"
{d.value:replace('cd', 1000)} // input: "abcdef abcde" → output: "ab1000ef ab1000e"
```

## :len

v2.0.0+

Returns the length of a string or array.

_Examples_

```javascript
{d.value:len()} // input: "Hello World" → output: 11
{d.value:len()} // input: "" → output: 0
{d.value:len()} // input: [1,2,3,4,5] → output: 5
{d.value:len()} // input: [1,"Hello"] → output: 2
```

## :t

v4.23.2+

Translate the text using the translation dictionnary

## :preserveCharRef

v4.23.8+

Preserve character reference

By default, Carbone removes all forbidden characters before injecting data into XML (e.g., &, >, <, �, ...).  
As a result, an injected character reference such as `&#xa7;` ( = `§` ) would be transformed into `&amp;#xa7;` in XML.  
This formatter prevents that transformation, preserving the character reference.

This function is useful for specific XML generation scenarios where the direct character cannot be used (e.g., non-UTF-8 charset),  
and the character reference must be retained.

It accepts numeric (e.g., `&#100;`) and hexadecimal formats (e.g., `&#xa10ef;`), in either lower or upper case.

## :formatR

Format a country/region code to a human readable region name

_Examples_

```javascript
// With API options: {
//   "lang": "en-us"
// }
{d.value:formatR()} // input: "US" → output: "United States of America"
{d.value:formatR()} // input: "DE" → output: "Germany"
{d.value:formatR()} // input: "FRA" → output: "France"
{d.value:formatR()} // input: "250" → output: "France"
{d.value:formatR()} // input: "276" → output: "Germany"
// With API options: {
//   "lang": "fr-fr"
// }
{d.value:formatR()} // input: "US" → output: "États-Unis d'Amérique"
{d.value:formatR()} // input: "DE" → output: "Allemagne"
{d.value:formatR()} // input: "FRA" → output: "France"
{d.value:formatR()} // input: "250" → output: "France"
{d.value:formatR()} // input: "276" → output: "Allemagne"
```

Get inspired by one of our real-life examples: [Summary](/examples/summary/index.md), [Mission Report](/examples/mission-report/index.md), [Grid Layout](/examples/matrix-pptx/index.md) or [Planning with subtotals](/examples/planification-medium/index.md)

## Related topics

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