# 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](/components/Avatar).


## 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

### Mobile

#### FormatFile

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `file` | `File | FileUpload` | Yes | — | File upload details object. Can be a File or a FileUpload |
| `accessibilityHint` | `string` | No | — | Accessibility hint |
| `accessibilityLabel` | `string` | No | — | Accessibility label |
| `bottomSheetOptionsSuffix` | `BottomSheetOptionsSuffix` | No | — | A file type to show at Bottom Sheet options |
| `createThumbnail` | `CreateThumbnail` | No | — |  |
| `onPreviewPress` | `(formattedFile: FormattedFile) => void` | No | — | Handler for the "Preview" Bottom Sheet Option press |
| `onRemove` | `() => void` | No | — | A function to be called on "Remove" Bottom Sheet Option press |
| `onTap` | `(file: T) => void` | No | — | A function which handles the onTap event. |
| `showFileTypeIndicator` | `boolean` | No | `true` | Set false to hide all file type iconography, including the video fallback placeholder icon. |
| `styleInGrid` | `boolean` | No | `false` | Uses a grid layout when multi-file upload is supported |
| `testID` | `string` | No | — | A reference to the element in the rendered output |

#### FormatFileContent

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `file` | `FormattedFile` | Yes | — |  |
| `isMedia` | `boolean` | Yes | — |  |
| `onUploadComplete` | `() => void` | Yes | — |  |
| `showOverlay` | `boolean` | Yes | — |  |
| `styleInGrid` | `boolean` | Yes | — |  |
| `accessibilityLabel` | `string` | No | — |  |
| `onMediaLoadEnd` | `() => void` | No | — | @internal A function to be called when the media has loaded. This is only used in FormatFileThumbnail. |
| `skipContainerStyles` | `boolean` | No | `false` | @internal When true, the component skips its container wrapper entirely (no border, background, or dimension styles).... |
| `surfaceColor` | `string` | No | — | Optional override for the tile's surface colour, forwarded to the underlying `FileView` or `MediaView`. Only meaningf... |