# FileSize
Package: @mantine/core
Import: import { FileSize } from '@mantine/core';
Description: 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:

```tsx
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`:

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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`:

```tsx
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:

```ts
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;
}
```


#### Props

**FileSize props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| locale | string | - | Locale used to format the number, uses the host default locale if not set |
| maximumFractionDigits | number | 2 | Maximum number of digits displayed after the decimal point |
| unit | "byte" \| "bit" | 'byte' | Unit that the value is measured in |
| unitDisplay | "short" \| "long" \| "narrow" | 'short' | Controls how the unit is displayed, `short` -> kB, `long` -> kilobytes, `narrow` -> kB |
| unitSystem | "decimal" \| "binary" | 'decimal' | Unit system used to scale the value: `decimal` (1000, kB/MB/GB) or `binary` (1024, KiB/MiB/GiB) |
| value | number | - | Value in bytes to format, or in bits when `unit="bit"` |