package
Format numbers with configurable decimal or binary unit prefixes for compact engineering output
npm install unitformatGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
25.2 kB
Includes dependencies.
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.
You can install UnitFormat.js via npm:
npm install unitformatOr with yarn:
yarn add unitformatAlternatively, download or clone the repository:
git clone https://github.com/rawify/UnitFormat.jsconst UnitFormat = require('unitformat');
const formatted = UnitFormat(10000);import UnitFormat, { UnitFormat as NamedUnitFormat } from 'unitformat';
const formatted = UnitFormat(10000);<script src="https://cdn.jsdelivr.net/npm/unitformat@1.1.5/dist/unitformat.min.js"></script>
<script>
const formatted = UnitFormat(10000);
</script><script type="module">
import UnitFormat from 'https://cdn.jsdelivr.net/npm/unitformat@1.1.5/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"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.
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 ....
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.
The whole package consists of a single function UnitFormat with the following signature
UnitFormat(num, baseUnit="", prefixes="kMGTPE", base=10)kMGTPE10 (default) or 2The suffix parameter is a string list of single-character metric prefixes, like kMGTPE. For base 10 the following prefixes can be used:
E: ExaP: PetaT: TeraG: GigaM: Megak: Kiloh: Hectod: Decic: Centim: Milliu: Micron: Nanop: Picof: Femtoa: AttoAnd for base 2 the following prefixes are possible:
k: KiloM: MegaG: GigaT: TeraP: PetaE: ExaThe 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 buildTesting the source against the shipped test suite is as easy as
npm run testCopyright (c) 2026, Robert Eisele Licensed under the MIT license.