/// Data Display
FormatByte
A deterministic file-size renderer — 1536 becomes 1.5 KB, in mono tabular figures.
import { FormatByte } from "@protocore/pds";Basics
Pass a byte count as value. It scales to the largest whole unit and renders mono tabular figures, so a column of sizes stays aligned. Sub-kilobyte values stay in whole bytes — you never see a fractional B.
Binary units and precision
binary switches to 1024-based IEC units (KiB, MiB, GiB) for the cases where that distinction matters — disk usage, memory. decimals sets the fractional precision on the scaled value.
The pure formatter
The math lives in an exported formatBytes(bytes, options) function — call it directly when you need the string outside JSX (a table cell value, a tooltip, an aria-label). Both the function and the component take an explicit locale (default "en") so a server render and its client hydration produce identical output.
A non-finite input renders the literal value with a data-invalid marker rather than fabricating an authoritative-looking size.
Usage
Do
- Pass a raw byte count and let the component pick the unit.
- Use `binary` for disk, memory, and anything the OS reports in KiB/MiB.
- Call `formatBytes` directly for strings outside JSX.
- Keep a fixed `locale` so SSR and client agree.
Don't
- Pre-divide the value; pass whole bytes.
- Mix binary and decimal units in one column; pick one basis.
- Expect fractional bytes; sub-KB values render as whole `B`.
Accessibility
- Renders a plain `<span>`; the formatted string is the accessible text.
- Mono tabular figures keep a column of sizes vertically aligned.
FormatByte props
| Prop | Type | Default | Description |
|---|---|---|---|
binary | boolean | false | Use 1024-based (IEC: KiB/MiB) units instead of 1000-based (KB/MB). |
className | string | — | |
decimals | number | 1 | Fractional digits on the scaled value. |
locale | string | "en" | BCP-47 locale for the decimal separator. Fixed so SSR and hydration agree. |
style | CSSProperties | — | |
value * | number | — | The size in bytes to format. |