FileSize

Format bytes into a human-readable file size

Usage

FileSize formats a number of bytes into a human-readable file size (1.45 kB, 4.8 GB). It renders text without a wrapping element:

FileSize
avatar.png15.36 kB
report.pdf1.45 MB
backup.zip4.8 GB
import { FileSize, Table } from '@mantine/core';

const files = [
  { name: 'avatar.png', size: 15360 },
  { name: 'report.pdf', size: 1_450_000 },
  { name: 'backup.zip', size: 4_800_000_000 },
];

function Demo() {
  return (
    <Table>
      <Table.Thead>
        <Table.Tr>
          <Table.Th>File</Table.Th>
          <Table.Th>Size</Table.Th>
        </Table.Tr>
      </Table.Thead>
      <Table.Tbody>
        {files.map((file) => (
          <Table.Tr key={file.name}>
            <Table.Td>{file.name}</Table.Td>
            <Table.Td>
              <FileSize value={file.size} />
            </Table.Td>
          </Table.Tr>
        ))}
      </Table.Tbody>
    </Table>
  );
}

SI (decimal) and binary units

By default, FileSize scales by 1000 and displays kB, MB, GB. Set unitSystem="binary" to scale by 1024 and display KiB, MiB, GiB:

BytesDecimal (SI)Binary
14501.45 kB1.42 KiB
10485761.05 MB1 MiB
15000000001.5 GB1.4 GiB
import { FileSize, Table } from '@mantine/core';

const values = [1450, 1_048_576, 1_500_000_000];

function Demo() {
  return (
    <Table withColumnBorders>
      <Table.Thead>
        <Table.Tr>
          <Table.Th>Bytes</Table.Th>
          <Table.Th>Decimal (SI)</Table.Th>
          <Table.Th>Binary</Table.Th>
        </Table.Tr>
      </Table.Thead>
      <Table.Tbody>
        {values.map((value) => (
          <Table.Tr key={value}>
            <Table.Td>{value}</Table.Td>
            <Table.Td>
              <FileSize value={value} unitSystem="decimal" />
            </Table.Td>
            <Table.Td>
              <FileSize value={value} unitSystem="binary" />
            </Table.Td>
          </Table.Tr>
        ))}
      </Table.Tbody>
    </Table>
  );
}

Bytes and bits

Set unit="bit" to measure the value in bits instead of bytes, for example to display network speed:

Storage: 8 MB

Throughput: 8 Mb

import { FileSize, Stack, Text } from '@mantine/core';

function Demo() {
  return (
    <Stack gap="xs">
      <Text>
        Storage: <FileSize value={8_000_000} unit="byte" />
      </Text>
      <Text>
        Throughput: <FileSize value={8_000_000} unit="bit" />
      </Text>
    </Stack>
  );
}

Unit display

Set unitDisplay to long (1.45 megabytes) or narrow (1.45MB) to change how the unit is rendered:

short: 1.45 MB

long: 1.45 megabytes

narrow: 1.45MB

import { FileSize, Stack, Text } from '@mantine/core';

function Demo() {
  return (
    <Stack gap="xs">
      <Text>
        short: <FileSize value={1_450_000} unitDisplay="short" />
      </Text>
      <Text>
        long: <FileSize value={1_450_000} unitDisplay="long" />
      </Text>
      <Text>
        narrow: <FileSize value={1_450_000} unitDisplay="narrow" />
      </Text>
    </Stack>
  );
}

Locale

Set locale to format the number for a specific locale. Always set it when rendering on the server, the server and client default locales may differ:

en-US: 1.45 MB

de-DE: 1,45 MB

fr-FR: 1,45 Mo

import { FileSize, Stack, Text } from '@mantine/core';

function Demo() {
  return (
    <Stack gap="xs">
      <Text>
        en-US: <FileSize value={1_450_000} locale="en-US" />
      </Text>
      <Text>
        de-DE: <FileSize value={1_450_000} locale="de-DE" />
      </Text>
      <Text>
        fr-FR: <FileSize value={1_450_000} locale="fr-FR" />
      </Text>
    </Stack>
  );
}

Maximum fraction digits

Use maximumFractionDigits to limit the number of digits after the decimal point:

import { FileSize } from '@mantine/core';

function Demo() {
  return <FileSize value={1_450_500} maximumFractionDigits={0} />; // -> 1 MB
}

formatBytes function

Use formatBytes when you need a string instead of a component, for example in aria-label:

Function callResult
formatBytes(1450)1.45 kB
formatBytes(1450, { unitSystem: 'binary' })1.42 KiB
formatBytes(8_000_000, { unit: 'bit' })8 Mb
formatBytes(1450, { locale: 'de-DE' })1,45 kB
import { formatBytes } from '@mantine/core';

formatBytes(1450);
formatBytes(1450, { unitSystem: 'binary' });
formatBytes(8_000_000, { unit: 'bit' });
formatBytes(1450, { locale: 'de-DE' });

formatBytes options

FileSize supports the same options as props:

interface FormatBytesOptions {
  /** Unit of the input value. Defaults to 'byte'. */
  unit?: 'byte' | 'bit';

  /** Scale by 1000 (decimal) or 1024 (binary). Defaults to 'decimal'. */
  unitSystem?: 'decimal' | 'binary';

  /** How to display the unit. Defaults to 'short'. */
  unitDisplay?: 'short' | 'long' | 'narrow';

  /** Locale for number formatting. Defaults to the host locale. */
  locale?: string;

  /** Maximum digits after the decimal point. Defaults to 2. */
  maximumFractionDigits?: number;
}