UnitFormat.js

UnitFormat.js is published as unitformat. Its single function scales a number and appends a selected decimal or binary prefix, producing compact values such as 1.3km, 1.5kB, or -1.5MW.

Use it for compact engineering labels, telemetry, file sizes, and chart axes when a fixed three-decimal rounding policy is acceptable.

Installation

You can install UnitFormat.js via npm:

npm install unitformat

Or with yarn:

yarn add unitformat

Alternatively, download or clone the repository:

git clone https://github.com/rawify/UnitFormat.js

Usage

CommonJS

const UnitFormat = require('unitformat');
const formatted = UnitFormat(10000);

ES modules

import UnitFormat, { UnitFormat as NamedUnitFormat } from 'unitformat';
const formatted = UnitFormat(10000);

Standalone browser script

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/unitformat.min.js"></script>
<script>
  const formatted = UnitFormat(10000);
</script>

Native browser module

<script type="module">
  import UnitFormat from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/unitformat.mjs';
  const formatted = UnitFormat(10000);
</script>

The package has no runtime dependencies and supports Node.js 20 or newer. CommonJS consumers can use the direct function export as well as its .default and .UnitFormat aliases. These compatibility paths are covered by the test suite and are part of the supported API.

The interface is a single function that takes the number to be formatted and optionally the base unit, such as m for meters:

const distance = UnitFormat(1000, 'm');   // "1km"
const frequency = UnitFormat(20000, 'Hz'); // "20kHz"
const scalar = UnitFormat(1000);           // "1k"
const small = UnitFormat(0.02, 'm');        // "0.02m"

Recipes

Format values with the default large SI prefixes

The default prefix set is kMGTPE; values below the base unit remain unscaled.

import UnitFormat from 'unitformat';

console.log(UnitFormat(1300, 'm'));       // "1.3km"
console.log(UnitFormat(-1_500_000, 'W')); // "-1.5MW"
console.log(UnitFormat(0.02, 'm'));       // "0.02m"

Results are strings rounded to at most three decimal places. Decimal digits, separators, and signs follow the runtime locale when locale formatting is available; otherwise a locale-neutral representation is used.

Enable small metric prefixes explicitly

The third argument is the exact set of allowed prefixes. Include c, m, u, or μ when values below one base unit should be scaled.

import UnitFormat from 'unitformat';

const prefixes = 'kMGTPEhdcmunpfa';

console.log(UnitFormat(0.02, 'm', prefixes));    // "2cm"
console.log(UnitFormat(0.00015, 'm', prefixes)); // "150um"
console.log(UnitFormat(0.000001, 'm', 'μ'));     // "1μm"

Prefix characters are case-sensitive. An unknown character throws Error: Unknown unit ....

Format binary-scaled byte counts

Pass base 2 to interpret k, M, and larger prefixes as powers of 1024.

import UnitFormat from 'unitformat';

console.log(UnitFormat(1024, 'B', 'kMGTPE', 2)); // "1kB"
console.log(UnitFormat(1536, 'B', 'kMGTPE', 2)); // "1.5kB"
console.log(UnitFormat(1024, 'B', 'kMGTPE', 10)); // "1.024kB"

Only bases 2 and 10 are supported; any other explicit base throws. The output uses the supplied symbols (kB, MB), not IEC labels such as KiB.

Available Parameters

The whole package consists of a single function UnitFormat with the following signature

UnitFormat(num, baseUnit="", prefixes="kMGTPE", base=10)

• num: the number to be formatted
• baseUnit: the base unit, like meters, Hertz, Joule, ...
• prefixes: allowed single-character prefixes; the default is kMGTPE
• base: scaling base, either 10 (default) or 2

Suffixes

The suffix parameter is a string list of single-character metric prefixes, like kMGTPE. For base 10 the following prefixes can be used:

• E: Exa
• P: Peta
• T: Tera
• G: Giga
• M: Mega
• k: Kilo
• h: Hecto
• d: Deci
• c: Centi
• m: Milli
• u: Micro
• n: Nano
• p: Pico
• f: Femto
• a: Atto

And for base 2 the following prefixes are possible:

• k: Kilo
• M: Mega
• G: Giga
• T: Tera
• P: Peta
• E: Exa

Building the library

The implementation is written in strict TypeScript. The build emits CommonJS, ES modules, a standalone browser bundle, source maps, and format-specific type declarations without modifying source or documentation files.

After cloning the Git repository, run:

npm install
npm run build

Run a test

Testing the source against the shipped test suite is as easy as

npm run test

Copyright and Licensing

Copyright (c) 2026, Robert Eisele Licensed under the MIT license.