human bytes

File sizes for humans.

See a live demo

• Install
• Example
• API
  • ESM
  • Common JS
  • humanBytes(num, opts)
  • Output Formats
  • More Examples
• Use
  • JS
  • Pre-built JS
• See Also

Install

npm i -S @substrate-system/human-bytes

Example

import { humanBytes } from '@substrate-system/human-bytes'

const readble = humanBytes(1337)
// => 1.34 kB

API

This exposes ESM and common JS via package.json exports field.

ESM

import '@substrate-system/human-bytes'

Common JS

require('@substrate-system/human-bytes')

humanBytes(num, opts)

humanBytes(n:number|bigint, options?:Options):string

Example

import { humanBytes } from '@substrate-system/human-bytes'

const result = humanBytes(1337)
// => '1.34 kB'

Parameters

num

The number to format. Can be either a number or bigint.

• Must be a finite number (throws TypeError for NaN, Infinity, or non-numeric values)
• Supports negative values
• Supports decimal values for number type

options (optional)

export interface Options {
    /**
     * Include plus sign for positive numbers. If the difference is exactly
     * zero a space character will be prepended instead for better alignment.
     * @default false
     */
    signed?:boolean

    /**
     * Format the number as bits instead of bytes. This can be useful when,
     * for example, referring to bit rate.
     * @default false
     */
    bits?:boolean

    /**
     * Format the number using the Binary Prefix instead of the SI Prefix.
     * This can be useful for presenting memory amounts.
     * However, this should not be used for presenting file sizes.
     * @default false
     */
    binary?:boolean

    /**
     * The minimum number of fraction digits to display.
     * If neither `minimumFractionDigits` or `maximumFractionDigits` are set,
     * the default behavior is to round to 3 significant digits.
     */
    minimumFractionDigits?:number

    /**
     * The maximum number of fraction digits to display.
     * If neither `minimumFractionDigits` or `maximumFractionDigits` are set,
     * the default behavior is to round to 3 significant digits.
     */
    maximumFractionDigits?:number

    /**
     * Put a space between the number and unit.
     * @default true
     */
    space?:boolean

    /**
     * Use a non-breaking space between the number and unit.
     * @default false
     */
    nonBreakingSpace?:boolean

    /**
     * The locale to use for number formatting.
     * - If `true`, the system default locale is used.
     * - If a string, the value is expected to be a locale-key
     *   (for example: `de`).
     * - If an array of strings, the first supported locale will be used.
     * @default false
     */
    locale?:string|string[]|boolean

    /**
     * Fixed width for the result string. The string will be padded with spaces
     * on the left if needed.
     */
    fixedWidth?:number
}

Output Formats

Return a human-readable string representation of the byte value. The output format depends on the options provided:

Default (SI Prefix, Bytes)

Uses base 1000 with standard byte units:

• B (Bytes)
• kB (Kilobytes)
• MB (Megabytes)
• GB (Gigabytes)
• TB (Terabytes)
• PB (Petabytes)
• EB (Exabytes)
• ZB (Zettabytes)
• YB (Yottabytes)

humanBytes(0)         // => '0 B'
humanBytes(999)       // => '999 B'
humanBytes(1000)      // => '1 kB'
humanBytes(1000000)   // => '1 MB'
humanBytes(1e16)      // => '10 PB'

Binary Prefix (base 1024)

Uses base 1024 with binary units:

• B (Bytes)
• KiB (Kibibytes)
• MiB (Mebibytes)
• GiB (Gibibytes)
• TiB (Tebibytes)
• PiB (Pebibytes)
• EiB (Exbibytes)
• ZiB (Zebibytes)
• YiB (Yobibytes)

humanBytes(1024, { binary: true })      // => '1 KiB'
humanBytes(1048576, { binary: true })   // => '1 MiB'
humanBytes(1e16, { binary: true })      // => '8.88 PiB'

Bits

Uses base 1000 with bit units:

• b (bits)
• kbit (kilobits)
• Mbit (megabits)
• Gbit (gigabits)
• Tbit (terabits)
• Pbit (petabits)
• Ebit (exabits)
• Zbit (zettabits)
• Ybit (yottabits)

humanBytes(1000, { bits: true })   // => '1 kbit'
humanBytes(1e16, { bits: true })   // => '10 Pbit'

Binary Bits

Uses base 1024 with binary bit units:

• b (bits)
• kibit (kibibits)
• Mibit (mebibits)
• Gibit (gibibits)
• Tibit (tebibits)
• Pibit (pebibits)
• Eibit (exbibits)
• Zibit (zebibits)
• Yibit (yobibits)

humanBytes(1024, { bits: true, binary: true })  // => '1 kibit'
humanBytes(1e6, { bits: true, binary: true })   // => '977 kibit'

More Examples

Combining Options

// Signed binary format with custom precision
humanBytes(42, { signed: true, binary: true, maximumFractionDigits: 2 })
// => '+42 B'

// Fixed width with locale formatting
humanBytes(1337, { fixedWidth: 10, locale: 'de' })
// => '   1,34 kB'

// Bits with no space
humanBytes(1500, { bits: true, space: false })
// => '1.5kbit'

// Negative numbers
humanBytes(-1000)
// => '-1 kB'

humanBytes(-1000, { signed: true })
// => '-1 kB'

BigInt Support

humanBytes(1337n)
// => '1.34 kB'

humanBytes(10n ** 16n)
// => '10 PB'

humanBytes(10n ** 30n, { binary: true })
// => '827181 YiB'

Use

JS

import '@substrate-system/human-bytes'

Pre-built JS

This package exposes minified JS files too. Copy them to a location that is accessible to your web server, then link to them in HTML.

copy

cp ./node_modules/@substrate-system/human-bytes/dist/index.min.js ./public/human-bytes.min.js

HTML

<script type="module" src="./human-bytes.min.js"></script>

See Also

The example page for this module uses a pretty checkbox, created by following this guide.

This is based on pretty-bytes by sindresorhus.