Nutritious Pomegranate Muffins

    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/byte-size package

    8.1.0 • Public • Published

    view on npm npm module downloads Gihub repo dependents Gihub package dependents Node.js CI Coverage Status js-standard-style

    Upgraders, please check the release notes.


    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 Yo yottaoctet
    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 Yio yobioctet


    By default, byteSize converts the input number to a human readable string with metric units and a precision of 1.

    > const byteSize = require('byte-size')
    > byteSize(1580)
    { value: '1.6', unit: 'kB', long: 'kilobytes' }

    The object returned by byteSize defines a toString method therefore can be used directly in string context.

    > `Filesize: ${byteSize(12400)}`
    'Filesize: 12.4 kB'

    Override the default toString behaviour by setting options.toStringFn.

    > function toStringFn () {
      return `**${this.value}${this.unit}**`
    > `Filesize: ${byteSize(12400, { toStringFn })}`
    'Filesize: **12.4kB**'

    Beside the default of metric, there are three other built-in units available: metric_octet, iec and iec_octet.

    > byteSize(1580, { units: 'iec' })
    { value: '1.5', unit: 'KiB', long: 'kibibytes' }
    > byteSize(1580, { units: 'iec_octet' })
    { value: '1.5', unit: 'Kio', long: 'kibioctets' }
    > byteSize(1580, { units: 'metric_octet' })
    { value: '1.6', unit: 'ko', long: 'kilooctets' }

    You can adjust the precision.

    > byteSize(1580, { units: 'iec', precision: 3 })
    { value: '1.543', unit: 'KiB', long: 'kibibytes' }
    > byteSize(1580, { units: 'iec', precision: 0 })
    { value: '2', unit: 'KiB', long: 'kibibytes' }

    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.

    > const customUnits = {
      simple: [
        { from: 0   , to: 1e3 , unit: ''  },
        { from: 1e3 , to: 1e6 , unit: 'K', long: 'thousand' },
        { from: 1e6 , to: 1e9 , unit: 'Mn', long: 'million' },
        { from: 1e9 , to: 1e12, unit: 'Bn', long: 'billion' }
    > const { value, unit } = byteSize(10000, { customUnits, units: 'simple' })
    > `${value}${unit}`

    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.

    > byteSize.defaultOptions({
      units: 'simple',
      precision: 2,
      customUnits: {
        simple: [
          { from: 0, to: 1e3, unit: '' },
          { from: 1e3, to: 1e6, unit: 'k' },
          { from: 1e6, to: 1e9, unit: 'm' },
          { from: 1e9, to: 1e12, unit: 'bn' },
      toStringFn: function () {
        return this.value + this.unit
    > [2400, 16400, 3991200].map(byteSize).join(', ')
    '2.40k, 16.40k, 3.99m'


    byteSize(bytes, [options]) ⇒ object

    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.
    [options.locale] string | Array.<string> 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().


    Set the default byteSize options for the duration of the process.

    Kind: static method of byteSize

    Param Type Description
    options object A byteSize options object.

    Load anywhere

    This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.

    Node.js (CommonJS):

    const byteSize = require('byte-size')

    Node.js (ECMAScript Module):

    import byteSize from 'byte-size'

    Within a modern browser ECMAScript Module:

    import byteSize from './node_modules/byte-size/index.js'

    Browser global (adds window.byteSize):

    <script src="./node_modules/byte-size/dist/index.js"></script>

    © 2014-21 Lloyd Brookes <>.

    Isomorphic test suite by test-runner and web-runner. Documented by jsdoc-to-markdown.


    npm i byte-size

    DownloadsWeekly Downloads






    Unpacked Size

    32.9 kB

    Total Files


    Last publish


    • 75lb