# File upload

> File upload is the control that lets people add a photo or a document, then shows the file and its progress. On a phone the selection itself is handed to a system picker and the app draws the surface around it.

Page: https://www.appetiteui.com/glossary/file-upload. File upload on mobile: photo picker and file states. Also called Upload, Attachment, Photo picker.

## Why it matters

The picker is the platform’s, so people already know it and a design only draws what happens before and after it: the invitation, the progress, the failure.

An upload can fail, so the error and the retry are part of the design and not an afterthought.

## iOS and Android

|  | iOS | Android (Material 3) | Appetite UI |
| --- | --- | --- | --- |
| Name | Document and photo pickers, Files app | No component in the file | File Upload |
| Selection | System document and photo pickers | Photo picker (PickVisualMedia), ACTION_OPEN_DOCUMENT as fallback | See below |
| States in the file | Default, Active, Disabled, Uploading, Upload, Error | Same six states | See below |

## In Appetite UI

File Upload has six states in two shapes. Default, Active and Disabled are the drop zone, which offers camera, photo library and files. Uploading, Upload and Error are the file row, which differ only in the second line and the action at the end.

The zone reads a label and supporting text, by default Upload a file and the accepted types and size.

## Example

A profile screen shows a drop zone reading Upload a photo. After a tap the system picker opens; the chosen file becomes a row with a progress line, and a failed upload turns the row into an error with a Retry action.

## Common mistakes

- Building a custom picker where the system one exists.
- No statement of accepted types and size before the upload.
- A progress row with no way to cancel.
- An error that does not say what to do. Offer Retry and name the cause.

## Questions

### How does Android pick photos?

With the photo picker through the PickVisualMedia contract. If it is not available on a device, the library falls back to the ACTION_OPEN_DOCUMENT intent.

### What states does a file upload need?

At least an invitation, a drag or press state, a disabled state, progress, success and error.

## Sources

1. [Apple Human Interface Guidelines: File management](https://developer.apple.com/design/human-interface-guidelines/file-management)
2. [Android Developers: Photo picker](https://developer.android.com/training/data-storage/shared/photopicker)

## Related

- Docs: [File Upload](https://www.appetiteui.com/docs/file-upload)
- Docs: [Progress](https://www.appetiteui.com/docs/progress)
- Glossary: [Progress indicator](https://www.appetiteui.com/glossary/progress-indicator)
- Glossary: [Toast and snackbar](https://www.appetiteui.com/glossary/toast-snackbar)
- Glossary: [Text field](https://www.appetiteui.com/glossary/text-field)