An isomorphic, load-anywhere function to convert a bytes value (e.g. 3456) to a human-readable string ('3.5 kB'). Choose between metric or IEC units (summarised below) or specify your own custom units.
Value
Metric
Metric (octet)
1000
kB kilobyte
ko kilooctet
1000^2
MB megabyte
Mo megaoctet
1000^3
GB gigabyte
Go gigaoctet
1000^4
TB terabyte
To teraoctet
1000^5
PB petabyte
Po petaoctet
1000^6
EB exabyte
Eo exaoctet
1000^7
ZB zettabyte
Zo zettaoctet
1000^8
YB yottabyte
Value
IEC
IEC (octet)
1024
KiB kibibyte
Kio kibioctet
1024^2
MiB mebibyte
Mio mebioctet
1024^3
GiB gibibyte
Gio gibioctet
1024^4
TiB tebibyte
Tio tebioctet
1024^5
PiB pebibyte
Pio pebioctet
1024^6
EiB exbibyte
Eio exbioctet
1024^7
ZiB zebibyte
Zio zebioctet
1024^8
YiB yobibyte
Synopsis
By default, byteSize converts the input number to a human readable string with metric units and a precision of 1.
Define custom units by passing an object containing one or more additional conversion tables to options.customUnits. In options.units, specify the name of a property from the customUnits object.
Override the built-in defaults for the duration of the process by passing an options object to byteSize.defaultOptions(). This results in cleaner code in cases where byteSize is used often with the same options.
Returns an object with the spec { value: string, unit: string, long: string }. The returned object defines a toString method meaning it can be used in any string context.
Kind: Exported function
Param
Type
Description
bytes
number
The bytes value to convert.
[options]
object
Optional config.
[options.precision]
number
Number of decimal places. Defaults to 1.
[options.units]
string
Specify 'metric', 'iec', 'metric_octet', 'iec_octet' or the name of a property from the custom units table in options.customUnits. Defaults to metric.
[options.customUnits]
object
An object containing one or more custom unit lookup tables.
[options.toStringFn]
function
A toString function to override the default.
byteSize.defaultOptions(options)
Set the default byteSize options for the duration of the process.
Node >=13 or modern browser only - on earlier platforms this option is ignored. The locale to use for number formatting (e.g. 'de-DE'). Defaults to your system locale. Passed directed into Intl.NumberFormat().