> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# File upload

> The File upload allows the user to upload files either by dragging and dropping files into the upload field or clicking to open the local system’s finder, allowing users to select and upload files from their computer or device.

<Badge color="orange">In progress</Badge> | *Storybook link coming soon*

## When to use

* When users need to submit documents, images, or other media.
* In forms or workflows that require file attachments (e.g., profile pictures, reports, invoices).
* When multiple files need to be uploaded efficiently and with clear feedback.

## When to use something else

* When an alternative method (e.g., selecting from a gallery, embedding links) is more efficient.
* For small text-based input: use an [Input](/cdf/aura/primitives/input) instead (e.g., entering a URL instead of uploading a document).
* If users will frequently reuse files, consider providing a file repository instead of requiring uploads each time.
* When real-time document collaboration is needed, opt for embedded editors instead.

## Dos and don'ts

* **Do** explicitly list file size limits and allowed formats upfront.
* **Do** show explicit visual progress indicators for active uploads.
* **Do** provide clear visual dropzone highlighting when a user drags a file over the target.
* **Do** allow users to cancel or pause ongoing uploads.
* **Do** validate file extensions and size limits on the client side before network requests.
* **Do** provide inline validation feedback on file uploads.
* **Don't** freeze or block the entire application UI during background transfers.
* **Don't** rely solely on drag-and-drop interactions without an explicit "Browse" button.
* **Don't** auto-dismiss upload completion or error banners before users read them.
* **Don't** truncate long file names without showing the full string on hover.

## Behavior

* Multi-file upload: If allowing multiple files to be uploaded, a list of uploaded files will appear below the File upload area. This ensures the user can still add more files later or remove specific files that are no longer needed.
* Single-file upload: If only one file is allowed to be uploaded, the File upload area is replaced by the uploaded file. This removes the possibility for the user to add additional files unless they remove the uploaded one.

## Often used with

[Label](/cdf/aura/primitives/label), [Helper text](/cdf/aura/primitives/helper-text); file list with remove actions; [Progress](/cdf/aura/primitives/progress) or inline status during upload.

## Accessibility

* **Connect custom dropzones:** Link custom visual dropzones to a native `<input type="file">`. Connect persistent helper text (for example file limits and formats) directly using `aria-describedby`.
* **Open the file picker from keyboard:** Ensure pressing Space or Enter on the dropzone or visual trigger opens the system file picker natively.
* **Announce upload status:** Wrap real-time progress, success notifications, and upload status changes in a container marked with `aria-live="polite"`.
* **Name removal controls:** Give every removal control in a multi-file queue a unique, context-aware accessible name (for example `aria-label="Remove invoice_2026.pdf"`).
* **Preserve focus on delete:** Direct focus to the removal button of the next file in the list, or back to the primary upload button, when a user deletes an uploaded item.
* **Link validation errors:** Flag validation failures with `aria-invalid="true"` and link inline error messages using `aria-errormessage`.