# @tsmx/human-readable > Easily create human-readable strings from byte sizes, e.g. 17238 --> 17.24 kB. Supports decimal (MB,GB,..) and binary (MiB, GiB,..) units as well as user-defined conversion from/to other sizes. Latest version **2.0.4** (published 2025-10-19) · MIT license · 0 weekly downloads ## Install ```sh npm install @tsmx/human-readable pnpm add @tsmx/human-readable yarn add @tsmx/human-readable bun add @tsmx/human-readable ``` ## Health **Score 65/100 (B)** — status: stable. Positive: has types; no vulnerabilities; has provenance; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 2.0.4 | | Published | 2025-10-19 | | First published | 2020-09-25 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=14.0.0 | | Dependencies | 0 | | Unpacked size | 19.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 5 | | Author | tsmx | | Maintainers | tsmx | | Keywords | human-readable, bytes, filesize, SI, IEC, conversion, decimal, binary, pretty-print | ## Links - npm: https://www.npmjs.com/package/@tsmx/human-readable - Repository: https://github.com/tsmx/human-readable - Homepage: https://tsmx.net/human-readable/ - Issues: https://github.com/tsmx/human-readable/issues - npm.io page: https://npm.io/package/@tsmx/human-readable ## Alternatives - [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads - [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads - [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads - [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads - [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads ## Recent versions - 2.0.4 (latest) — 2025-10-19 - 2.0.3 — 2024-06-18 - 2.0.2 — 2023-11-19 - 2.0.1 — 2023-06-19 - 2.0.0 — 2023-06-05 - 1.0.9 — 2023-04-26 - 1.0.8 — 2022-12-20 - 1.0.7 — 2021-08-21 - 1.0.6 — 2021-05-30 - 1.0.5 — 2020-11-22 - 1.0.4 — 2020-10-11 - 1.0.3 — 2020-09-27 - 1.0.2 — 2020-09-25 - 1.0.1 — 2020-09-25 - 1.0.0 — 2020-09-25 ## README # [**@tsmx/human-readable**](https://github.com/tsmx/human-readable) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) ![npm (scoped)](https://img.shields.io/npm/v/@tsmx/human-readable) ![node-current (scoped)](https://img.shields.io/node/v/@tsmx/human-readable) [![Build Status](https://img.shields.io/github/actions/workflow/status/tsmx/human-readable/git-build.yml?branch=master)](https://img.shields.io/github/actions/workflow/status/tsmx/human-readable/git-build.yml?branch=master) [![Coverage Status](https://coveralls.io/repos/github/tsmx/human-readable/badge.svg?branch=master)](https://coveralls.io/github/tsmx/human-readable?branch=master) > Easily create human-readable strings from byte sizes, e.g. `17238` → `17.24 kB`. Supports decimal (MB,GB,..) and binary (MiB, GiB,..) units as well as user-defined conversion from/to other sizes. For details about the differences of decimal (SI) and binary (IEC) units please refer to [Wikipedia](https://en.wikipedia.org/wiki/Byte). Also check out the [full documentation](https://tsmx.net/human-readable/). Type declarations for seamless usage in TypeScript projects are included. If you need to use this package on the client-side in the browser using plain JavaScript, refer to [this article](https://tsmx.net/npm-packages-browser/). ## Usage ```js const hr = require('@tsmx/human-readable'); hr.fromBytes(17238); // '17.24 kB' hr.fromBytes(17238, { mode: 'IEC' }); // '16.83 KiB' hr.fromBytes(17238, { numberOnly: true }); // '17.24' hr.fromBytes(17238, { fixedPrecision: 1 }); // '17.2 kB' hr.fromBytes(17238, { fullPrecision: true }); // '17.238 kB' hr.fromTo(17, 'GBYTE', 'KBYTE'); // '17000000 kB' hr.fromTo(17, 'GBYTE', 'KBYTE', { mode: 'IEC' }); // '17825792 KiB' hr.availableSizes(); // [ 'BYTE', 'KBYTE', 'MBYTE', 'GBYTE', 'TBYTE', 'PBYTE' ] ``` ## API ### fromBytes(bytes, options) Automatically creates a human-readable string out of a given number of bytes. E.g. `71255` → `71.26 kB` #### bytes Type: `Number` Amount of bytes. #### options Type: `Object` Optional. ##### mode Type: `String` Default: none (use decimal mode) Can be set to `IEC` to use binary conversion (factor 1.024) and units (KiB,MiB,...). If not set or to any other value, decimal conversion (factor 1.000) and units (kB, MB,...) are used. ##### numberOnly Type: `Boolean` Default: `false` If set to true, conversion only returns the number and omits the unit. Overrides `noWhitespace`. ##### fixedPrecision Type: `Number` If set the returned number string is formatted to the given fixed decimal places. If not set, the default behaviour of the conversion is to use a dynamic number of decimal places from zero up to two. ##### fullPrecision Type: `Boolean` Default: `false` If set to true, the returned number value will be presented with full available decimal places. Overrides `fixedPrecision`. ##### noWhitespace Type: `Boolean` Default: `false` If set to true, the whitespace between the number and unit string is omitted. E.g. `10MB` instead of `10 MB`. ### fromTo(value, fromSize, toSize, options) Converts a value from a given size unit to a human-readable string of the target size. E.g. converting Gigabytes to Megabytes. #### value Type: `Number` The value to be converted. #### fromSize Type: `String` The size `value` has. Must be one out of `availableSizes`. #### toSize Type: `String` The size `value` should be converted to. Must be one out of `availableSizes`. #### options Type: `Object` See options description under `fromBytes`. ### availableSizes() Returns an array of strings of all available sizes. --- _Source: https://npm.io/package/@tsmx/human-readable · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._