# simplur

> Simple, versatile string pluralization

Latest version **4.1.1** (published 2026-05-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install simplur
pnpm add simplur
yarn add simplur
bun add simplur
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2026-05-07 |
| First published | 2019-11-02 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 7.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 16 |
| Author | Robert Kieffer |
| Maintainers | broofa |
| Keywords | pluralize, pluralise, plural, plur, inflection, inflector |

## Links

- npm: https://www.npmjs.com/package/simplur
- Repository: https://github.com/broofa/simplur
- Homepage: https://github.com/broofa/simplur#readme
- Issues: https://github.com/broofa/simplur/issues
- npm.io page: https://npm.io/package/simplur

## Dependencies (1)

- [commitlint](https://npm.io/package/commitlint.md) 20.5.3

## Recent versions

- 4.1.1 (latest) — 2026-05-07
- 4.1.0 — 2026-02-18
- 4.0.0 — 2024-04-17
- 3.0.1 — 2021-06-02
- 3.0.0 — 2020-10-11
- 2.0.0 — 2020-10-01
- 1.1.0 — 2020-02-14
- 1.0.6 — 2019-11-02
- 1.0.5 — 2019-11-02
- 1.0.4 — 2019-11-02

## README

<!--
  -- This file is auto-generated from README_js.md. Changes should be made there.
  -->

# Simplur

Simple, versatile string pluralization

## Upgrading to Version 4

`simplur@4` has no API changes from version 3. The only change is it is now ESM-only. (I.e. CommonJS is no longer supported.) [ESM Module FAQ](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).

## Installation

```
npm i simplur
```

```javascript
import simplur from 'simplur';
```

## Usage

`simplur` is an ES6 [template tag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) that formats pluralization tokens based on the quantities injected into the string.

> [!IMPORTANT]
>
> Quantities must either be `number`s (simple case) or `Array`s.  Other types will be ignored.


### Simple case

Pluralization tokens have the form "`[singular|plural]`" and are resolved
using the first expression found to the left of each token or, if no
left-expression is available, the first expression to the right.

```javascript
simplur`I have ${1} kitt[en|ies]`; // ⇨ 'I have 1 kitten'
simplur`I have ${3} kitt[en|ies]`; // ⇨ 'I have 3 kitties'

simplur`There [is|are] ${1} m[an|en]`; // ⇨ 'There is 1 man'
simplur`There [is|are] ${5} m[an|en]`; // ⇨ 'There are 5 men'
```

### Multiple tokens

Multiple tokens and quantities are allowed. These follow the same rules as above.

```javascript
simplur`There [is|are] ${1} fox[|es] and ${4} octop[us|i]`; // ⇨ 'There is 1 fox and 4 octopi'
simplur`There [is|are] ${4} fox[|es] and ${1} octop[us|i]`; // ⇨ 'There are 4 foxes and 1 octopus'
```

### Tokens as expressions
`simplur` inlines all `string` template values prior to processing, allowing you
to pass pluralization tokens as values.

```javascript
const pets = ['dog[|s]', 'lazy cat[|s]', 'wily fox[|es]'];

simplur`I love my ${3} ${pets[1]}`; // ⇨ 'I love my 3 lazy cats'
```

### Custom quantities

Quantity values may be customized using value of the form, `[quantity, format function]`. For example:

```javascript
function format(qty) {
  return qty == 1 ? 'sole' : qty == 2 ? 'twin' : qty;
}

simplur`Her ${[1, format]} br[other|ethren] left`; // ⇨ 'Her sole brother left'
simplur`Her ${[2, format]} br[other|ethren] left`; // ⇨ 'Her twin brethren left'
simplur`Her ${[3, format]} br[other|ethren] left`; // ⇨ 'Her 3 brethren left'
```

#### Hiding quantities

Quantities may be hidden by omitting the format function (i.e. just pass the
value in an `Array`), or by returning `null` or `undefined` from the quantity
function.

**Note:** _Whitespace immediately following a hidden quantity will be removed._

```javascript
simplur`${[1]} gen[us|era]`; // ⇨ 'genus'
simplur`${[2]} gen[us|era]`; // ⇨ 'genera'

function hideSingular(qty) {
  return qty == 1 ? null : qty;
}

simplur`Delete the ${[1, hideSingular]} cact[us|i]?`; // ⇨ 'Delete the cactus?'
simplur`Delete the ${[2, hideSingular]} cact[us|i]?`; // ⇨ 'Delete the 2 cacti?'
```

Custom

---

Markdown generated from [README_js.md](README_js.md) by [![RunMD Logo](http://i.imgur.com/h0FVyzU.png)](https://github.com/broofa/runmd)

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