Filesize.js: Format Bytes as Readable File Sizes

Authoravoidwork

Last UpdateJune 26, 2026

LicenseMIT

Features:

Convert raw byte counts into readable file size labels.
Format bit totals for bandwidth displays.
Switch among SI, IEC, and JEDEC unit systems.
Return strings, arrays, objects, or unit exponents.
Format localized values and custom unit labels.
Reuse fixed formatting rules across repeated values.
Accept number and BigInt input.
Run in browser and Node.js projects.

Use Cases:

Multi-file upload queues show a readable size next to each selected File before the upload begins.
Storage quota cards present occupied and remaining capacity with one consistent IEC formatter.
Media dashboards convert API byte totals into localized labels for each account.
Network diagnostics display transferred byte counts as bit values when the interface reports throughput.
Download components use structured value and symbol fields when the number and unit need separate styling.

How To Use It

Installation

Install filesize with npm and import it into your JavaScript or TypeScript projects.

npm install filesize

import { filesize, partial } from "filesize";

You can also load the UMD build for regular browser pages. You must call window.filesize.filesize() instead of treating filesize as a direct global function.

<script src="/dist/filesize.umd.min.js"></script>
<script>
  // Format a byte total from a backup record.
  const backupLabel = window.filesize.filesize(2_621_440, {
    standard: "iec",
  });
  document.querySelector("#backup-size").textContent = backupLabel;
</script>

Basic Usage

Pass a byte value to filesize() and store the readable result.

import { filesize } from "filesize";
// Raw size from an uploaded file or API response.
const archiveBytes = 6_842_368;
// IEC units use KiB, MiB, GiB, and other 1024-based labels.
const archiveLabel = filesize(archiveBytes, {
  standard: "iec",
});
console.log(archiveLabel); // "6.53 MiB"

Advanced Usages

Format File API values

Browser File.size values already use bytes. Pass that value directly into filesize and choose IEC units when the interface describes computer storage.

import { filesize } from "filesize";
const selectedFile = document.querySelector("#document-upload").files[0];
const readableSize = filesize(selectedFile.size, {
  standard: "iec",
  round: 1,
});
console.log(readableSize); // Example: "4.8 MiB"

Reuse one storage formatter

Storage dashboards often render many values with the same unit system and precision. Create the formatter once and call it for every quota, backup, or download record.

import { partial } from "filesize";
// Keep all storage values on the same IEC formatting policy.
const formatStorage = partial({
  standard: "iec",
  round: 1,
});
const usedSpace = formatStorage(18_874_368_000);
const remainingSpace = formatStorage(4_294_967_296);
console.log(usedSpace);
console.log(remainingSpace);

Return separate number and unit values

A component may need separate elements for the numeric value and the unit. Object output avoids string splitting in the render layer.

import { filesize } from "filesize";
const reportSize = filesize(52_428_800, {
  standard: "iec",
  output: "object",
  round: 1,
});
console.log(reportSize.value); // 50
console.log(reportSize.symbol); // "MiB"
console.log(reportSize.exponent); // 2

Display bit values

Set the bit option when the UI needs bit units.

import { filesize } from "filesize";
const transferredBits = filesize(125_000_000, {
  bits: true,
  standard: "si",
  round: 0,
});
console.log(transferredBits); // "1 Gbit"

Localize file size labels

Set the locale explicitly in server-rendered applications so the server and browser return the same label.

import { filesize } from "filesize";
const localizedSize = filesize(37_452_008, {
  standard: "si",
  locale: "de-DE",
  localeOptions: {
    maximumFractionDigits: 1,
  },
});
console.log(localizedSize); // "37,5 MB"

All Configuration Options

bits (boolean): Converts the input from bytes to bits before formatting. Defaults to false.
base (number): Sets the numeric base. Use 2 for binary calculations, 10 for decimal calculations, or -1 for automatic selection.
round (number): Sets the maximum number of decimal places. Defaults to 2.
locale (string | boolean): Applies locale-aware number formatting. Pass a BCP 47 locale string or true for the runtime locale.
localeOptions (object): Passes additional Intl.NumberFormat options when locale uses a locale string.
separator (string): Replaces the decimal separator when locale formatting is not active.
spacer (string): Controls the text between the number and unit. Defaults to one space.
symbols (object): Replaces built-in byte or bit unit labels with custom symbols.
standard (string): Selects the unit system. Supported values include si, iec, and jedec.
output (string): Selects string, array, object, or exponent output.
fullform (boolean): Uses full unit names such as kilobytes or kibibytes.
fullforms (array): Replaces the full unit names with custom labels.
exponent (number): Forces a specific unit exponent. Use -1 for automatic selection.
roundingMethod (string): Chooses round, floor, or ceil.
precision (number): Sets the number of significant digits. Use 0 for automatic behavior.
pad (boolean): Preserves trailing decimal places up to the configured rounding value.

API Methods

import { filesize, partial } from "filesize";
// Converts a number or BigInt byte value into the selected output format.
const fileLabel = filesize(8_388_608, {
  standard: "iec",
  round: 2,
});
// Returns a reusable formatter with fixed options.
const formatArchiveSize = partial({
  standard: "iec",
  round: 1,
});
// Formats each value with the saved configuration.
const archiveLabel = formatArchiveSize(18_874_368);

Implementation Tips

Pass File.size and most storage API values directly because they already represent bytes.
Use standard: "iec" when the UI must show 1024-based values such as KiB, MiB, and GiB.
Use standard: "si" when the interface follows decimal storage values such as kB, MB, and GB.
Keep locale explicit in SSR applications. Runtime locale differences can create hydration mismatches.
Cache a partial() formatter in lists, tables, and dashboards that format many values.
The library accepts BigInt input, but its current implementation converts that value to a JavaScript Number. Do not depend on exact precision for values beyond Number.MAX_SAFE_INTEGER.
Do not append /s automatically for transfer rates. filesize formats the numeric byte or bit value only.

Alternatives:

FAQs:

Q: Why does filesize() throw a TypeError?
A: filesize() throws a TypeError when the input is not a valid number or BigInt, or when it receives an unsupported roundingMethod value. Check the input type before calling the function when values come from user input or an API response.

Q: How do I match the binary units shown in Windows or macOS?
A: Set standard to iec to get KiB, MiB, and GiB units. Pair it with base: 2 for correct binary calculation.

Q: Can I pass File.size directly to filesize?
A: Yes. The browser File API reports file size in bytes, so filesize(file.size) works directly in upload interfaces.

Q: Which output mode works best for a component that styles the value and unit separately?
A: Use output: "object". It returns separate value, symbol, exponent, and unit fields.

Q: How do I display a value in bits per second?
A: Set bits: true and, if needed, adjust the base. For example, filesize(1000000, { bits: true, spacer: "/s" }) produces a string like "8 Mbit/s". You can further customize the unit symbols with the symbols option.

Q: Why is the locale formatting slow, and what should I use instead?
A: Locale formatting delegates to the browser’s Intl API, which is more expensive than simple number operations. Use locale only when you need region‑specific number formatting. In high‑throughput code, apply the locale formatting on the raw numeric result separately or cache the pre‑formatted strings.