or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-pretty-bytes

Convert bytes to a human readable string with appropriate unit suffixes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pretty-bytes@7.0.x

To install, run

npx @tessl/cli install tessl/npm-pretty-bytes@7.0.0

index.mddocs/

Pretty Bytes

Pretty Bytes is a lightweight JavaScript/TypeScript library that converts numeric byte values into human-readable string representations with appropriate unit suffixes. It provides comprehensive formatting options including binary vs decimal prefixes, bit vs byte units, localization support, and customizable precision control.

Package Information

  • Package Name: pretty-bytes
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install pretty-bytes

Core Imports

import prettyBytes from "pretty-bytes";

For CommonJS:

const prettyBytes = require("pretty-bytes");

Basic Usage

import prettyBytes from "pretty-bytes";

// Basic byte conversion
prettyBytes(1337);
//=> '1.34 kB'

prettyBytes(100);
//=> '100 B'

// Large numbers with BigInt support
prettyBytes(10n ** 16n);
//=> '10 PB'

// Display with units of bits
prettyBytes(1337, {bits: true});
//=> '1.34 kbit'

// Display file size differences with signed numbers
prettyBytes(42, {signed: true});
//=> '+42 B'

// Localized output using German locale
prettyBytes(1337, {locale: 'de'});
//=> '1,34 kB'

// Binary prefixes for memory amounts
prettyBytes(1024, {binary: true});
//=> '1 KiB'

// Custom precision control
prettyBytes(1900, {maximumFractionDigits: 1});
//=> '1.9 kB'

// No space between number and unit
prettyBytes(1920, {space: false});
//=> '1.92kB'

Capabilities

Byte Conversion Function

Converts bytes to a human readable string with comprehensive formatting options.

/**
 * Convert bytes to a human readable string: 1337 → 1.34 kB
 * @param number - The number to format (supports number and bigint)
 * @param options - Optional configuration object
 * @returns Formatted string with number and unit suffix
 * @throws TypeError for non-finite numbers or invalid input types
 */
function prettyBytes(
  number: number | bigint,
  options?: Options
): string;

Parameters:

  • number: The numeric value to format. Accepts both regular JavaScript numbers and BigInt values for handling very large numbers
  • options: Optional configuration object controlling formatting behavior

Returns: A formatted string containing the number with appropriate unit suffix (B, kB, MB, GB, etc.)

Throws: TypeError when:

  • Input is not a finite number (NaN, Infinity, -Infinity)
  • Input is not a number or bigint (strings, booleans, null, undefined, objects)

Usage Examples:

// Basic conversions
prettyBytes(0);           //=> '0 B'
prettyBytes(999);         //=> '999 B' 
prettyBytes(1001);        //=> '1 kB'
prettyBytes(1e16);        //=> '10 PB'
prettyBytes(1e30);        //=> '1000000 YB'

// BigInt support for very large numbers
prettyBytes(0n);          //=> '0 B'
prettyBytes(10n ** 16n);  //=> '10 PB'
prettyBytes(10n ** 30n);  //=> '1000000 YB'

// Negative numbers
prettyBytes(-999);        //=> '-999 B'
prettyBytes(-1001);       //=> '-1 kB'

// Decimal values
prettyBytes(0.4);         //=> '0.4 B'
prettyBytes(10.1);        //=> '10.1 B'

Options Interface

Complete configuration options for customizing byte formatting behavior.

interface Options {
  /** Include plus sign for positive numbers. Zero displays with space for alignment */
  readonly signed?: boolean;
  
  /** Localization settings for number formatting */
  readonly locale?: boolean | string | readonly string[] | undefined;
  
  /** Format as bits instead of bytes */
  readonly bits?: boolean;
  
  /** Use binary prefixes (KiB, MiB) instead of SI prefixes (kB, MB) */ 
  readonly binary?: boolean;
  
  /** Minimum number of fraction digits to display */
  readonly minimumFractionDigits?: number;
  
  /** Maximum number of fraction digits to display */
  readonly maximumFractionDigits?: number;
  
  /** Put space between number and unit */
  readonly space?: boolean;
}

signed Option

Include plus sign for positive numbers. When the value is exactly zero, a space character is prepended instead for better alignment.

  • Type: boolean
  • Default: false
prettyBytes(42, {signed: true});    //=> '+42 B' (space: true is default)
prettyBytes(-13, {signed: true});   //=> '-13 B'  
prettyBytes(0, {signed: true});     //=> ' 0 B' (leading space for alignment)

locale Option

Controls number localization using BCP 47 language tags. Only the number and decimal separator are localized - unit titles remain in English.

  • Type: boolean | string | readonly string[]
  • Default: false (no localization)

Values:

  • false: No localization
  • true: Use system/browser default locale
  • string: BCP 47 language tag (e.g., 'de', 'en', 'fr')
  • string[]: Array of BCP 47 language tags with fallbacks
  • undefined: Same behavior as false (no localization)
prettyBytes(1337, {locale: 'de'});                    //=> '1,34 kB'
prettyBytes(1337, {locale: 'en'});                    //=> '1.34 kB'
prettyBytes(1e30, {locale: 'de'});                    //=> '1.000.000 YB'
prettyBytes(1337, {locale: ['unknown', 'de', 'en']}); //=> '1,34 kB'
prettyBytes(1337, {locale: true});                    //=> '1.34 kB' (system locale)
prettyBytes(1337, {locale: undefined});               //=> '1.34 kB' (no localization)

bits Option

Format the number as bits instead of bytes. Useful for bit rates and network speeds.

  • Type: boolean
  • Default: false
prettyBytes(1337, {bits: true});    //=> '1.34 kbit'
prettyBytes(1e16, {bits: true});    //=> '10 Pbit'
prettyBytes(999, {bits: true});     //=> '999 b'

binary Option

Use binary prefixes (base-2, powers of 1024) instead of SI prefixes (base-10, powers of 1000). Recommended for memory amounts but not file sizes as per industry standards.

  • Type: boolean
  • Default: false

Binary prefixes: B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB (base-1024) SI prefixes: B, kB, MB, GB, TB, PB, EB, ZB, YB (base-1000)

prettyBytes(1000, {binary: true});   //=> '1000 B'
prettyBytes(1024, {binary: true});   //=> '1 KiB'
prettyBytes(1e16, {binary: true});   //=> '8.88 PiB'

// Combined with bits option
prettyBytes(1025, {bits: true, binary: true}); //=> '1 kibit'

minimumFractionDigits Option

The minimum number of fraction digits to display. Works with JavaScript's toLocaleString method.

  • Type: number
  • Default: undefined

When neither minimumFractionDigits nor maximumFractionDigits are set, the default behavior rounds to 3 significant digits.

prettyBytes(1900, {minimumFractionDigits: 3}); //=> '1.900 kB'
prettyBytes(1900);                             //=> '1.9 kB'
prettyBytes(1000, {minimumFractionDigits: 1}); //=> '1.0 kB'

maximumFractionDigits Option

The maximum number of fraction digits to display. Works with JavaScript's toLocaleString method.

  • Type: number
  • Default: undefined

When neither minimumFractionDigits nor maximumFractionDigits are set, the default behavior rounds to 3 significant digits.

prettyBytes(1920, {maximumFractionDigits: 1}); //=> '1.9 kB'
prettyBytes(1920);                             //=> '1.92 kB'
prettyBytes(1111, {maximumFractionDigits: 2}); //=> '1.11 kB'

// Combined minimum and maximum
prettyBytes(1000, {
  minimumFractionDigits: 1,
  maximumFractionDigits: 3
}); //=> '1.0 kB'

space Option

Controls whether to put a space between the number and unit.

  • Type: boolean
  • Default: true
prettyBytes(1920, {space: false}); //=> '1.92kB'
prettyBytes(1920);                 //=> '1.92 kB' (space: true is default)
prettyBytes(42, {signed: true, space: false}); //=> '+42B'
prettyBytes(0, {signed: true, space: false});  //=> ' 0B' (leading space preserved)

Error Handling

The function validates input and throws descriptive errors for invalid data:

// These will throw TypeError
prettyBytes('');                    // string input
prettyBytes('1');                   // string input  
prettyBytes(Number.NaN);           // NaN
prettyBytes(Number.POSITIVE_INFINITY); // Infinity
prettyBytes(Number.NEGATIVE_INFINITY); // -Infinity
prettyBytes(true);                 // boolean
prettyBytes(null);                 // null
prettyBytes(undefined);            // undefined

Error message format: "Expected a finite number, got <type>: <value>"

Unit Systems

Pretty Bytes supports multiple unit systems depending on the bits and binary options:

Byte Units (default)

SI Prefixes (decimal, base-1000): B, kB, MB, GB, TB, PB, EB, ZB, YB Binary Prefixes (base-1024): B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB

Bit Units (bits: true)

SI Prefixes (decimal, base-1000): b, kbit, Mbit, Gbit, Tbit, Pbit, Ebit, Zbit, Ybit Binary Prefixes (base-1024): b, kibit, Mibit, Gibit, Tibit, Pibit, Eibit, Zibit, Yibit

Advanced Usage Patterns

Handling Very Large Numbers

// BigInt for numbers beyond JavaScript's safe integer limit
const veryLarge = 9007199254740991n * 1000000n;
prettyBytes(veryLarge); //=> Appropriate unit conversion

// Scientific notation
prettyBytes(1e30);      //=> '1000000 YB'
prettyBytes(827_181 * 1e26); //=> '82718100 YB'

Localization with Different Regions

// German formatting
prettyBytes(1e30, {locale: 'de'}); //=> '1.000.000 YB'

// English formatting  
prettyBytes(1e30, {locale: 'en'}); //=> '1,000,000 YB'

// Fallback locale handling
prettyBytes(1001, {locale: ['unknown', 'de', 'en']}); //=> '1 kB'

Memory vs File Size Formatting

// File sizes (use SI prefixes - default)
prettyBytes(1000);                  //=> '1 kB'
prettyBytes(1000000);               //=> '1 MB' 

// Memory amounts (use binary prefixes)
prettyBytes(1024, {binary: true});  //=> '1 KiB'
prettyBytes(1048576, {binary: true}); //=> '1 MiB'

Network/Speed Formatting

// Bit rates for network speeds
prettyBytes(1000000, {bits: true}); //=> '1 Mbit'
prettyBytes(1000, {bits: true});    //=> '1 kbit'

// Data transfer amounts
prettyBytes(1337, {signed: true});  //=> '+1.34 kB' (positive transfer)
prettyBytes(-1337, {signed: true}); //=> '-1.34 kB' (negative transfer)