# template-format

> Simple string formatting with support for nested data.

Latest version **2.0.0** (published 2026-08-16) · ISC license · 0 weekly downloads

## Install

```sh
npm install template-format
pnpm add template-format
yarn add template-format
bun add template-format
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-08-16 |
| First published | 2016-12-09 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 6.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Eduard Castellano |
| Maintainers | educastellano |

## Links

- npm: https://www.npmjs.com/package/template-format
- Repository: https://github.com/educastellano/template-format
- Homepage: https://github.com/educastellano/template-format#readme
- Issues: https://github.com/educastellano/template-format/issues
- npm.io page: https://npm.io/package/template-format

## Recent versions

- 2.0.0 (latest) — 2026-08-16
- 1.2.5 — 2019-12-03
- 1.2.4 — 2019-09-03
- 1.2.3 — 2019-09-03
- 1.2.2 — 2019-03-04
- 1.2.1 — 2019-03-04
- 1.2.0 — 2018-03-21
- 1.1.0 — 2017-09-13
- 1.0.1 — 2016-12-12
- 1.0.0 — 2016-12-09

## README

# template-format

Simple string formatting with support for nested data.

## Install

```sh
npm install template-format
```

## Syntax

```js
const formattedText = format(text, data, options)
```

| Parameter                 | Type      | Default      | Description                                                                                                                                            |
| ------------------------- | --------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text`                    | `string`  |              | Text to format                                                                                                                                         |
| `object`                  | `object`  |              | The object or array containing the data to be used for formatting.                                                                                     |
| `options`                 | `object`  | `{}`         | **Optional** Extra options, read below.                                                                                                                |
| `options.regex`           | `regex`   | `/{(.*?)}/g` | **Optional** Alternative regex for different format syntaxes _(i.e.: `Hello {{name}}!`)_. Must include the global match modifier (`g`).                |
| `options.skipUndefined`   | `boolean` | `false`      | **Optional** Skips formatting parameters which are missing in the object, keeping the original text. Otherwise they'll be replaced by an empty string. |
| `options.spreadToken`     | `string`  | `$n`         | **Optional** Token used on arrays to indicate that the following attributes have to be applied in each element (See example below).                    |
| `options.spreadSeparator` | `string`  | `,`          | **Optional** String used on arrays to separate of the formatting in each element.                                                                      |

## Usage

```js
import format from 'template-format'
```

**With objects**

```js
format('Hello {name}, happy {age} bday!', { name: 'Bob', age: 32 })
// 'Hello Bob, happy 32 bday!'
```

**With arrays**

```js
format('Hello {0}, happy {1} bday!', ['Bob', 32])
// 'Hello Bob, happy 32 bday!'
```

**With nested data**

```js
format('Hello {bob.name}, happy {bob.age} bday! I call you at {bob.contact.phone}', {
  bob: {
    name: 'Bob',
    age: 32,
    contact: {
      phone: '978090909'
    }
  }
})
// 'Hello Bob, happy 32 bday! I call you at 978090909'
```

**Spread arrays**

```js
format('Hello {people.$n.name}!', { people: [{ name: 'Bob' }, { name: 'Mary' }] })
// 'Hello Bob,Mary!'
```

**Other Options**

- Skip undefined attributes:

```js
format('Hello {name}, happy {age} bday!', { name: 'Bob' })
// 'Hello Bob, happy bday!'
```

```js
format('Hello {name}, happy {age} bday!', { name: 'Bob' }, { skipUndefined: true })
// 'Hello Bob, happy {age} bday!'
```

- Using a different format syntax:

```js
format('Hello {{name}}, happy {{age}} bday!', { name: 'Bob', age: 32 }, { regex: /{{(.*?)}}/g })
// 'Hello Bob, happy 32 bday!'
```

- Custom spreading

```js
format(
  'Hello {people.$$.name}!',
  { people: [{ name: 'Bob' }, { name: 'Mary' }] },
  { spreadToken: '$$', spreadSeparator: ', ' }
)
// 'Hello Bob, Mary!'
```

## Changelog

- 2.0.0
  - Remove build step and babel deps
  - Replace tape for brittle, add lunte, prettier and CI
  - Fix skipUndefined mishandling falsy values
- 1.2.0
  - Support to spread formatting on arrays
  - Customizable spreading with `spreadToken` and `spreadSeparator`

- 1.1.0
  - Support to skip `undefined` attributes
  - Support for alternative format syntaxes

- 1.0.0
  - Initial release :tada:

## License

[ISC License](http://opensource.org/licenses/ISC)

---
_Source: https://npm.io/package/template-format · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._