Format Numbers with Metric Prefixes in JavaScript – UnitFormat.js

UnitFormat.js is a lightweight number formatting utility that converts raw numeric values into human-readable units with proper metric prefixes like 10km, 5GB, 17kHz, or 220MW.

It’s great for displaying large numbers in user interfaces, dashboards, or data visualizations where space is limited and readability matters.

Features:

• Automatic prefix selection: Chooses the most appropriate metric prefix based on number magnitude.
• Dual base support: Handles both decimal (base-10) and binary (base-2) number systems.
• Custom unit specification: Accepts any base unit like meters, Hertz, bytes, or watts.
• Configurable prefix sets: Allows selection of specific metric prefixes for different use cases.
• Zero-dependency implementation: Works without external libraries or frameworks.
• Universal module support: Compatible with CommonJS, ES modules, and browser globals.

How to use it:

1. Install UnitFormat and import it into your project.

# Yarn
$ yarn add unitformat
# NPM
$ npm install unitformat

// ES6 import
import UnitFormat from 'unitformat';
// CommonJS require
const UnitFormat = require('unitformat');

2. For browser-based projects, include the unitformat.min.js file directly.

<script src="unitformat.js"></script>

3. Format your numeric values using the UnitFormat function:

• num: The number you want to format.
• baseUnit (optional): A string for the base unit, like “m”, “B”, or “Hz”. It gets appended after the metric prefix. Defaults to an empty string.
• prefixes (optional): A string containing the single-character metric prefixes you want to allow, in order of preference. The default is "kMGTPE".
• base (optional): The numerical base for calculations. It defaults to 10 but can be set to 2 for binary units like bytes.

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

UnitFormat(1000) → "1k"
UnitFormat(0.02, "m") → "2cm"
UnitFormat(1048576, "B", "kMGTPE", 2) → "1MB"
UnitFormat(12345, "W", "kM") → "12.345kW"
UnitFormat(-5000000, "J") → "-5MJ"

4. You have a wide range of suffixes to choose from depending on the base.

For Base 10:

• E: Exa (10^18)
• P: Peta (10^15)
• T: Tera (10^12)
• G: Giga (10^9)
• M: Mega (10^6)
• k: Kilo (10^3)
• h: Hecto (10^2)
• d: Deci (10^-1)
• c: Centi (10^-2)
• m: Milli (10^-3)
• u or μ: Micro (10^-6)
• n: Nano (10^-9)
• p: Pico (10^-12)
• f: Femto (10^-15)
• a: Atto (10^-18)

For Base 2:

• E: Exa (2^60)
• P: Peta (2^50)
• T: Tera (2^40)
• G: Giga (2^30)
• M: Mega (2^20)
• k: Kilo (2^10)

FAQs

Q: Can I use custom units beyond the standard metric prefixes?
A: UnitFormat.js only supports the predefined metric prefixes listed in its internal tables. You cannot add custom prefixes, but you can restrict which prefixes are used by modifying the prefixes parameter.

Q: How does the library handle very large or very small numbers?
A: The function will use the largest available prefix from your specified set. If your number exceeds the range of available prefixes, it will format with the largest prefix available, which might result in large coefficients like “5000E” for extremely large values.

Q: Does UnitFormat.js handle localization or different decimal separators?
A: No, the library always outputs numbers with standard decimal points and does not support localization features. You would need to post-process the output for different locale requirements.

Q: What happens with negative numbers?
A: The function correctly handles negative values by preserving the negative sign and applying the same formatting logic to the absolute value. For example, -1000 with unit “m” becomes “-1km”.

Q: Can I format percentages or currency values?
A: UnitFormat.js is designed specifically for metric prefix formatting and does not include percentage or currency formatting capabilities. You’ll need a different library for those use cases.

Q: How does the base-2 mode differ from base-10 for file sizes?
A: Base-2 uses 1024 as the multiplier (1kB = 1024 bytes), while base-10 uses 1000 (1kB = 1000 bytes). The base-2 mode is more accurate for computer storage systems, while base-10 aligns with SI standard definitions.