📐 @alimuhnad/ngx-filesize

Angular v20 standalone pipe to format file sizes (Bytes → KB, MB, GB, TB).

• i18n-ready via Intl.NumberFormat (Arabic digits supported)
• Treeshakable, SSR-safe, zero dependencies

Table of contents

• Features
• Install
• Quick start
• Usage
• API
• Internationalization (Arabic)
• SSR & performance notes
• Compatibility
• Troubleshooting
• Examples
• Contributing
• License
• ملخص عربي

Features

✅ Angular v20 standalone pipe (no NgModule)
🌍 i18n-friendly using Intl.NumberFormat (Arabic digits when locale is ar)
🔢 Configurable fraction digits (e.g., 1.23 MB)
🧩 Zero runtime deps; treeshakable; ESM
🧠 Safe defaults for invalid/zero values

Install

npm i @alimuhnad/ngx-filesize

Angular 20+ is required (see Compatibility).

Quick start

If you want Arabic digits/formatting, register the Arabic locale once (optional):

// main.ts
import { bootstrapApplication, LOCALE_ID } from '@angular/core';
import { registerLocaleData } from '@angular/common';
import ar from '@angular/common/locales/ar';

registerLocaleData(ar);

bootstrapApplication(AppComponent, {
  providers: [{ provide: LOCALE_ID, useValue: 'ar' }]
});

Then import the pipe directly in any standalone component:

import { Component } from '@angular/core';
import { FileSizePipe } from '@alimuhnad/ngx-filesize';

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [FileSizePipe],
  template: `
    <p>Size: {{ bytes | filesize }}</p>
  `
})
export class DemoComponent {
  bytes = 1_048_576; // 1 MB
}

Usage

<!-- Uses app LOCALE_ID or falls back to 'en' -->
<span>{{ 1048576 | filesize }}</span>           <!-- "1 MB" or "١ MB" -->

<!-- Force English regardless of app locale -->
<span>{{ 123456789 | filesize:'en' }}</span>    <!-- "117.7 MB" -->

<!-- Control fraction digits -->
<span>{{ 123456789 | filesize:'en':1 }}</span>  <!-- "117.7 MB" -->
<span>{{ 123456789 | filesize:'ar':3 }}</span>  <!-- "١١٧٫٧٣٧ MB" (digits localized) -->

Note: Units are standardized Latin (B, KB, MB, GB, TB). Numerals respect the selected locale.

API

filesize pipe

Formats a numeric byte value into a human-readable string.

Signature

transform(
  value: number,
  locale: string = 'en',
  digits: number = 2
): string

Params

• value: Byte count (number). If NaN, returns empty string.
• locale: BCP-47 locale (e.g., 'en', 'ar').
• digits: 0..3 recommended — used as maximumFractionDigits.

Returns

• Formatted string like "1.2 MB", with numerals localized via Intl.NumberFormat.

Internationalization (Arabic)

When LOCALE_ID starts with 'ar' and you’ve called registerLocaleData(ar), numerals render using Arabic digits:

<span>{{ 1048576 | filesize:'ar' }}</span> <!-- "١ MB" -->

• Units remain Latin by design (KB, MB, …) for cross-language consistency.
• If you need Arabic unit words (مثل: "بايت، كيلوبايت، ميغابايت") يمكنك التفاف النتائج مخصصًا في تطبيقك (انظر Examples).

SSR & performance notes

• The pipe is pure and performs a single computation per value.
• SSR-safe: no timers or browser-only APIs beyond Intl.NumberFormat.
• For large lists, prefer OnPush components and avoid re-creating numbers every CD cycle.

Compatibility

• Angular: v20+
• TypeScript: 5.x+
• Runtime: Modern browsers / Node with Intl.NumberFormat
• Dependencies: none (uses tslib via Angular workspace)

Troubleshooting

“I get an empty string”
Ensure the input is a valid number (not null/undefined/string). Coerce if needed: +size.

“Why are units Latin?”
This library localizes digits; units are standardized (KB, MB, …). See the example below to map units to Arabic words if desired.

“Rounding looks off”
Adjust digits param: | filesize:'en':0 for integers, :1 or :2 for finer precision.

Examples

Force Arabic digits while keeping English app locale

{{ 5_242_880 | filesize:'ar' }}  <!-- "٥ MB" -->

Map units to Arabic words (app-level wrapper)

// example.util.ts
const UNIT_MAP_AR: Record<string, string> = {
  B: 'بايت', KB: 'كيلوبايت', MB: 'ميغابايت', GB: 'غيغابايت', TB: 'تيرابايت'
};

export function arabicUnits(label: string) {
  return label.replace(/\b(B|KB|MB|GB|TB)\b/g, (u) => UNIT_MAP_AR[u]);
}

<!-- First format normally, then post-process the unit label -->
<span>{{ arabicUnits((123456789 | filesize:'ar':1)) }}</span>
<!-- "١١٧٫٧ ميغابايت" -->

Table cell with exact bytes in title attribute

<td [attr.title]="bytes + ' B'">
  {{ bytes | filesize:'en':2 }}
</td>

Contributing

PRs and issues are welcome!
If you propose new options (e.g., unit localization), please include tests and docs.

Local dev

# build the library from workspace root
ng build ngx-filesize

# pack & consume in a demo app
cd dist/ngx-filesize
npm pack
# in your app:
npm i ../path/to/ngx-filesize-*.tgz

License

MIT © Ali Muhnad

ملخص عربي (Quick Start)

• ثبّت الحزمة: npm i @alimuhnad/ngx-filesize
• (اختياري) فعّل العربية:

  registerLocaleData(ar);
  providers: [{ provide: LOCALE_ID, useValue: 'ar' }];

• أمثلة:

  {{ 1048576 | filesize }}          <!-- 1 MB / ١ MB -->
  {{ 123456789 | filesize:'en':1 }} <!-- 117.7 MB -->
  {{ 123456789 | filesize:'ar':1 }} <!-- ١١٧٫٧ MB -->