# Format File

FormatFile will take a file object and display it in a number of lifecycle
states. It can be used to display a file that has been uploaded, or to display a
file that is about to be uploaded, as indicated by the progress indicator.

## Design & usage guidelines

When contributing to, or consuming the FormatFile component, consider the
following:

* FormatFile components should take up the full width of the parent container (1
  or 2 files per row)
* The delete button will only be displayed if the callback function is passed in

When using FormatFile for web, files can be displayed as either expanded or
compact. A compact FormatFile is used to display a cropped version of a file or
image, while expanded is used to display a file alongside its metadata.

## Related components

* For a thumbnail representation of a user, use [Avatar](../Avatar/Avatar.md).


## Developer notes

`FormatFileThumbnail` distinguishes between a real video thumbnail and a video
file that has no preview image available.

When a video has a valid `thumbnailUrl` or decodable source, Atlantis renders
the thumbnail and overlays the existing small `video` icon. When no preview is
available, Atlantis renders a fallback placeholder and shows the `videoFile`
icon by default instead of showing the OS broken-image glyph.

`showFileTypeIndicator={false}` hides all file type iconography, including the
large `videoFile` icon used by video placeholders.

Use `surfaceColor` on `FormatFileThumbnail` when the tile needs to visually
blend into surrounding chrome:

```tsx
<FormatFileThumbnail
  file={file}
  size={{ width: 96, height: 96 }}
  surfaceColor="var(--color-surface)"
/>
```


## Props

### Web

#### FormatFile

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `file` | `FileUpload` | Yes | — | File upload details object. (See FileUpload type.) |
| `display` | `"compact" | "expanded"` | No | `expanded` | To display as either a file row or thumbnail |
| `displaySize` | `"base" | "large"` | No | `base` | The base dimensions of the thumbnail |
| `onClick` | `(event: MouseEvent<HTMLButtonElement | HTMLDivElement, MouseEvent>) => void` | No | — | Function to execute when format file is clicked |
| `onDelete` | `() => void` | No | — | onDelete callback - this function will be called when the delete action is triggered |

#### FormatFile.Body

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `isComplete` | `boolean` | Yes | — |  |
| `ariaBusy` | `boolean` | No | — |  |
| `className` | `string` | No | — |  |
| `onClick` | `MouseEventHandler<HTMLButtonElement | HTMLDivElement>` | No | — |  |
| `tabIndex` | `number` | No | — |  |
| `type` | `"button" | "reset" | "submit"` | No | — |  |

#### FormatFile.DeleteButton

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `onDelete` | `(event: MouseEvent<HTMLButtonElement, MouseEvent>) => void` | No | — |  |

#### FormatFile.DeleteButtonContainer

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |
| `isHidden` | `boolean` | No | — |  |

#### FormatFile.Expanded

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `file` | `FileUpload` | Yes | — |  |
| `fileSize` | `string` | Yes | — |  |
| `isVisible` | `boolean` | Yes | — |  |

#### FormatFile.ProgressContainer

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |
| `isHidden` | `boolean` | No | — |  |

#### FormatFile.ThumbnailContainer

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |

#### FormatFile.Wrapper

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `className` | `string` | No | — |  |