# human-format

> Converts a number to/from a human readable string: `1337` ↔ `1.34kB`

Latest version **1.2.1** (published 2024-11-06) · ISC license · 0 weekly downloads

## Install

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

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.1 |
| Published | 2024-11-06 |
| First published | 2014-03-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 0 |
| Unpacked size | 16.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 100 |
| Author | Julien Fontanet |
| Maintainers | julien-f, marsaud, pdonias |
| Keywords | byte, bytes, file, filesize, human, humanized, pretty, readable, si, size, unit |

## Links

- npm: https://www.npmjs.com/package/human-format
- Repository: https://github.com/JsCommunity/human-format
- Issues: https://github.com/JsCommunity/human-format/issues
- npm.io page: https://npm.io/package/human-format

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 1.2.1 (latest) — 2024-11-06
- 1.2.0 — 2023-04-11
- 1.1.0 — 2023-03-29
- 1.0.0 — 2022-03-14
- 0.11.0 — 2020-06-17
- 0.10.1 — 2018-10-04
- 0.10.0 — 2018-01-10
- 0.9.2 — 2017-12-14
- 0.9.1 — 2017-12-13
- 0.9.0 — 2017-11-08
- 0.8.0 — 2017-03-01
- 0.7.0 — 2016-09-22
- 0.6.0 — 2015-12-16
- 0.5.1 — 2015-12-01
- 0.5.0 — 2015-08-28
- … 7 more at https://npm.io/package/human-format/versions

## README

# human-format

[![Build Status](https://img.shields.io/travis/JsCommunity/human-format/master.svg)](http://travis-ci.org/JsCommunity/human-format)
[![Dependency Status](https://david-dm.org/JsCommunity/human-format/status.svg?theme=shields.io)](https://david-dm.org/JsCommunity/human-format)
[![devDependency Status](https://david-dm.org/JsCommunity/human-format/dev-status.svg?theme=shields.io)](https://david-dm.org/JsCommunity/human-format#info=devDependencies)

> Converts a number to/from a human readable string: `1337` ↔ `1.34kB`

## Installation

### Node & [Browserify](http://browserify.org/)/[Webpack](https://webpack.js.org/)

Installation of the [npm package](https://npmjs.org/package/human-format):

```
> npm install --save human-format
```

Then require the package:

```javascript
var humanFormat = require("human-format");
```

### Browser

You can directly use the build provided at [unpkg.com](https://unpkg.com/human-format/):

```html
<script src="https://unpkg.com/human-format@1/index.js"></script>
```

## Usage

### Formatting

```javascript
humanFormat(1337);
//=> '1.34 k'

// The maximum number of decimals can be changed.
humanFormat(1337, {
  maxDecimals: 1,
});
//=> '1.3 k'

// maxDecimals can be set to auto, so that there is 1 decimal between -10 and 10 excluded and none out of this interval.
humanFormat(1337, {
  maxDecimals: "auto",
});
//=> '1.3 k'

humanFormat(13337, {
  maxDecimals: "auto",
});
//=> '13 k'

// A fixed number of decimals can be set.
humanFormat(1337, {
  decimals: 4,
});
//=> '1.3370 k'

// Units and scales can be specified.
humanFormat(65536, {
  scale: "binary",
  unit: "B",
});
//=> 64 kiB

// There is a helper for this.
humanFormat.bytes(65536);
//=> 64 kiB

// A custom separator can be specified.
humanFormat(1337, {
  separator: " - ",
});
//=> 1.34 - k

// Custom scales can be created!
var timeScale = new humanFormat.Scale({
  seconds: 1,
  minutes: 60,
  hours: 3600,
  days: 86400,
  months: 2592000,
});
humanFormat(26729235, { scale: timeScale });
//=> 10.31 months

// Helper when the scale is regular, i.e. prefixes are powers of a constant factor
var binaryScale = humanFormat.Scale.create(["", "Ki", "Mi", "Gi", "Ti"], 1024);
humanFormat(173559053, { scale: binaryScale });
//=> 165.52 Mi

// You can force a prefix to be used.
humanFormat(100, { unit: "m", prefix: "k" });
//=> 0.1 km

// You can access the raw result.
humanFormat.raw(100, { prefix: "k" });
//=> {
//   prefix: 'k',
//   value: 0.09999999999999999 // Close value, not rounded.
// }
```

### Parsing

```javascript
humanFormat.parse("1.34 kiB", { scale: "binary" });
//=> 1372.16

// Fallbacks when possible if the prefix is incorrectly cased.
humanFormat.parse("1 g");
// => 1000000000

// You can access the raw result.
humanFormat.parse.raw("1.34 kB");
//=> {
//  factor: 1000,
//  prefix: 'k',
//  unit: 'B',
//  value: 1.34
//}
```

## Contributions

Contributions are _very_ welcomed, either on the documentation or on
the code.

You may:

- report any [issue](https://github.com/JsCommunity/human-format/issues)
  you've encountered;
- fork and create a pull request.

Contributors:

- @djulien
- @qrohlf
- @Itay289
- @sweetpi

## License

ISC © [Julien Fontanet](http://julien.isonoe.net)

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