# File Uploader

The File Uploader component allows users to easily upload documents and images through drag-and-drop, browse, or click actions. Built with accessibility and clarity in mind, this component ensures seamless interaction, feedback on file status, and visual clarity. It accommodates various upload needs like single, multiple, or preview-based, with consistent interaction feedback.

<figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FRNRMGb5ljji8e8ix6VKY%2Fimage.png?alt=media&#x26;token=ca72a48d-c5f3-4099-8347-df0fa4a1c583" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="Component React" %}

```
// Sample code

<FileUpload
  multiple
  showDownloadButton
  showReUploadButton
  uploadedFiles={[]}
  validations={{
    maxSizeAllowedInMB: 5,
    minSizeRequiredInMB: 1
  }}
  variant="uploadWidget"
/>
```

{% endtab %}

{% tab title="Component Flutter" %}

```
// Sample code

FileUpload(
        allowMultiples: true,
        label: 'Upload', 
        onFilesSelected: (List<PlatformFile> files) {
            Map<PlatformFile, String?> fileErrors = {};

            return fileErrors;
        },
        openFile: true,
        showPreview: true,
        errorMessage: 'Error Message',
      ),
```

{% endtab %}

{% tab title="Component Design" %}

{% endtab %}
{% endtabs %}

## Anatomy

<figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FsPXhNaqJpz3bLRN5H2nj%2Fimage.png?alt=media&#x26;token=ac604500-cb77-4def-b472-003da78d59b9" alt=""><figcaption></figcaption></figure>

***

## Variants

***

<table data-header-hidden><thead><tr><th width="321"></th><th></th></tr></thead><tbody><tr><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FreXIDCDVRrBDvmrErl46%2Fimage.png?alt=media&#x26;token=cdecb72a-9d86-4322-b10b-127cf811f137" alt=""><figcaption></figcaption></figure></div></td><td><p><strong>Uploader Field</strong></p><p>A compact file upload input paired with an action button. Best suited for single file uploads in form layouts.</p></td></tr><tr><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FgS0JsdI7McLrToraqgQU%2Fimage.png?alt=media&#x26;token=58274033-97ba-4176-9ea9-6696f9ecfc1a" alt=""><figcaption></figcaption></figure></div></td><td><p><strong>Uploader Widget</strong></p><p>A more interactive drag-and-drop style uploader. Useful when multiple files need to be uploaded or where visual cues are important.</p></td></tr><tr><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FwphOQirRblmnAWDvRRKS%2Fimage.png?alt=media&#x26;token=677766ff-af1a-4774-bbe7-358dcb8dda8f" alt=""><figcaption></figcaption></figure></div></td><td><p><strong>Image Upload</strong></p><p>A visual first variant designed to upload and preview images. Users can click to add, preview thumbnails, or remove images directly.</p></td></tr></tbody></table>

***

## Interaction States

<table><thead><tr><th width="334.98046875"></th><th></th></tr></thead><tbody><tr><td><p><strong>Hover State for Multiple Image Load</strong></p><p>When the user hovers over the field or an item, it highlights to indicate interactivity and help the user discover selectable areas.</p></td><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FHLSRvV5Mq6p63bjWWDj1%2Fimage.png?alt=media&#x26;token=2d869c71-9159-4767-93c8-71afeac11934" alt=""><figcaption></figcaption></figure></div></td></tr><tr><td><p><strong>Mouse Down State for Multiple Image Load</strong></p><p>When the user performs a mouse-down action on the Image Upload area, a contextual menu appears offering multiple options for uploading. This menu typically includes:
<br>Camera – Opens the device’s camera to capture and upload a new image instantly.<br>My Files – Opens the file explorer or gallery to choose existing images from the device.
<br>This interaction provides flexibility and enhances the upload experience, especially on mobile devices or when real-time photo capture is required.</p></td><td><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FTkhn135LhQKaarmhzT2b%2Fimage.png?alt=media&#x26;token=3c53f26d-fc49-4d3e-9217-7c23ef01a9ab" alt=""><figcaption></figcaption></figure></div></td></tr></tbody></table>

## Properties

|                                                                                                                                                                    |                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <p><strong>Single Upload</strong></p><p>Allows only one file to be uploaded at a time. Automatically replaces existing files.</p>                                  | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FKfxypU7zHnQYRFdjhVza%2Fimage.png?alt=media&#x26;token=51f44b1a-1251-442d-b5e7-3a67c2e8271c" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Multiple Upload</strong></p><p>Enables uploading of several files. Each file is shown with a re-upload and download option.</p>                         | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2Fln2sT15Yw9eyt6pgOjP1%2Fimage.png?alt=media&#x26;token=9184c9e2-3437-4e03-b43d-5af95bc8db6b" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Error</strong></p><p>Displays error messages per file or globally. Indicates upload failure, unsupported format, or size limit.</p>                     | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FY9e1AgdMWzOyWLK2pSRL%2Fimage.png?alt=media&#x26;token=ce29d378-7083-4d5f-b437-f560929974fd" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Label</strong></p><p>Each uploader can have a custom label to define the upload purpose clearly.</p>                                                    | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FaBdzrS1l8VvJFr1GxWej%2Fimage.png?alt=media&#x26;token=710a9fd5-9018-4552-82f2-e4cacfff6b39" alt=""><figcaption></figcaption></figure></div> |
| <p><strong>Actions</strong></p><p>Includes an option to upload using the “device camera” and “my files” options, only applicable for the image upload variant.</p> | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FkeDe1wV9fdxR20cOBTv6%2Fimage.png?alt=media&#x26;token=2277eb09-b92f-4b12-a2f9-75986423abc4" alt=""><figcaption></figcaption></figure></div> |

## Property Configuration Table

Each design component offers a range of configurable options. These options are intentionally platform-agnostic, allowing implementations to adapt and tailor them to align with the specific requirements of the chosen framework.

{% tabs %}
{% tab title="React" %}

<table><thead><tr><th width="257">Property</th><th>Value</th><th>Default</th></tr></thead><tbody><tr><td>variant</td><td>text</td><td></td></tr><tr><td>multiple</td><td>text</td><td></td></tr><tr><td>onUpload</td><td>yes/no</td><td>no</td></tr><tr><td>validations</td><td>yes/no</td><td>no</td></tr><tr><td>removeTargetedFile</td><td>number</td><td></td></tr><tr><td>showHint</td><td>yes/no</td><td></td></tr><tr><td>showLabel</td><td>yes/no</td><td>no</td></tr><tr><td>accept</td><td>yes/no</td><td>no</td></tr><tr><td>additionalElements</td><td>yes/no</td><td>no</td></tr><tr><td>showErrorCard</td><td>number</td><td>no</td></tr><tr><td>iserror</td><td>yes/no</td><td>no</td></tr><tr><td>showDownloadButton</td><td>text</td><td>no</td></tr><tr><td>showReUploadButton</td><td>yes/no</td><td>no</td></tr><tr><td>customClass</td><td>yes/no</td><td></td></tr><tr><td>disabled</td><td>yes/no</td><td></td></tr><tr><td>style</td><td>yes/no</td><td></td></tr><tr><td>id</td><td>yes/no</td><td></td></tr><tr><td>extraStyles</td><td>yes/no</td><td></td></tr><tr><td>disabledButton</td><td>yes/no</td><td></td></tr><tr><td>textStyles</td><td>yes/no</td><td></td></tr><tr><td>buttonType</td><td>yes/no</td><td></td></tr><tr><td>showAsTags</td><td>yes/no</td><td></td></tr><tr><td>showAsPreview</td><td>yes/no</td><td></td></tr><tr><td>inline</td><td>yes/no</td><td></td></tr><tr><td>label</td><td>yes/no</td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Flutter" %}

<table><thead><tr><th>Property</th><th width="209">Value</th><th>Default</th></tr></thead><tbody><tr><td>onFilesSelected</td><td>OnFilesSelectedCallback</td><td>required</td></tr><tr><td>label</td><td>String</td><td>required</td></tr><tr><td>errorMessage</td><td>String</td><td>-</td></tr><tr><td>downloadText</td><td>String</td><td>-</td></tr><tr><td>isErrorChip</td><td>bool</td><td>-</td></tr><tr><td>reUploadText</td><td>String</td><td>-</td></tr><tr><td>showPreview</td><td>bool</td><td>false</td></tr><tr><td>allowMultiples</td><td>bool</td><td>false</td></tr><tr><td>cameraTitle</td><td>String</td><td>-</td></tr><tr><td>galleryTitle</td><td>String</td><td>-</td></tr><tr><td>cancelText</td><td>String</td><td>-</td></tr><tr><td>captureText</td><td>String</td><td>-</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

## Behaviours

|                                                                                                                                                                                                                                                                                            |                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FNhPzEfeCDhcWbsJqZiyC%2Fimage.png?alt=media&#x26;token=5ffb88cc-352e-412b-ae52-25366ca86945" alt=""><figcaption></figcaption></figure></div> | <p><strong>Drag & Drop Support</strong></p><p>Uploader Widget allows users to drag and drop files into the designated area.</p> |

***

## Usage Guide

***

| <p><strong>Allow to preview uploaded files</strong></p><p>Provide a thumbnail or preview option for the uploaded images. This helps users verify that they uploaded the correct file before submitting it.</p><p></p><p>Avoid using generic error messages like "Upload failed" without explanation. Users need to know why their file wasn't accepted and what they should do next.</p> | <p></p><div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FNFfUZX2IfWge4bHMQjnw%2Fimage.png?alt=media&#x26;token=587bebcb-11c3-4c83-a5d7-e3e88702ae0f" alt=""><figcaption></figcaption></figure></div> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|                                                                                                                                                                                                                                                                                                                                                                                          | <div><figure><img src="https://3868804918-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FegsIWleSdyH9rMLJ8ShI%2Fuploads%2FO2OMIm0GiKiiZdHvXMsn%2Fimage.png?alt=media&#x26;token=d050eb30-92dc-4455-8929-0ca776ac2331" alt=""><figcaption></figcaption></figure></div>        |

## Changelog

***

| Date         | Number  | Notes                                                                                           |
| ------------ | ------- | ----------------------------------------------------------------------------------------------- |
| Dec 15, 2024 | v-0.0.2 | <p>This component is added to the website.<br>This component is now individually versioned.</p> |

## Design Checklist

***

<table data-header-hidden><thead><tr><th width="129" data-type="checkbox"></th><th></th></tr></thead><tbody><tr><td>true</td><td><strong>All interactive states</strong> - Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).</td></tr><tr><td>true</td><td><strong>Accessible use of colours</strong> - Colour is not used as the only visual means of conveying information (WCAG 2.1 1.4.1)</td></tr><tr><td>true</td><td><strong>Accessible contrast for text</strong> - Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).</td></tr><tr><td>true</td><td><strong>Accessible contrast for UI components</strong> - Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).</td></tr><tr><td>true</td><td><strong>Keyboard interactions</strong> - Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).</td></tr><tr><td>false</td><td><strong>Screen reader accessible</strong> - All content, including headings, labels, and descriptions, is meaningful, concise, contextual and accessible by screen readers.</td></tr><tr><td>true</td><td><strong>Responsive for all breakpoints</strong> - Responsiveness for 3 breakpoints - Mobile, Tablet and Desktop</td></tr><tr><td>true</td><td><strong>Usage guidelines</strong> - Includes a list of dos and don'ts that highlight best practices and common mistakes.</td></tr><tr><td>false</td><td><strong>Writing guidelines</strong> - Content standards and usage guidelines for writing and formatting in-product content for the component.</td></tr><tr><td>true</td><td><strong>Defined variants and properties</strong> - Includes relevant variants and properties (style, size, orientation, optional iconography, decorative elements, selection states, error states, etc.)</td></tr><tr><td>true</td><td><strong>Defined behaviours</strong> - Guidelines for keyboard navigation and focus, layout management (including wrapping, truncation, and overflow), animations, and user interactions.</td></tr><tr><td>true</td><td><strong>Design Kit</strong> - Access to the design file for the component in Figma, multiple options, states, colour themes, and platform scales.</td></tr></tbody></table>