File upload

Preview

When to use

Use the file upload component when the user needs to attach one or more files as part of a form or task. Common use cases:

• Uploading a profile photo or avatar.
• Attaching a receipt, invoice, or document.
• Submitting an image or file for review.

When not to use

• Don't use this component for actions that don't involve file system files (e.g., selecting from a gallery within the app — use a different selection pattern).
• Avoid using it when an inline text entry or URL input would serve the same purpose more simply.

Behaviour

The component presents a clickable drop zone. The user can either click to open the system file picker or drag and drop a file into the area.

Once a file is selected, the component transitions from the empty state to the filled state, displaying the selected file name. The user can remove the file and select a different one.

If the file fails validation (wrong type, too large), the component shows an error state with a message explaining the problem.

Anatomy

• Drop zone — the clickable and draggable target area. Displays instructions and an upload icon in the empty state.
• Label — a form field label above the drop zone that describes what file is expected.
• Helper text (optional) — guidance below the drop zone (e.g., accepted formats, max file size).
• File item — shown in the filled state; displays the selected file name and a remove button.
• Error message — appears below the drop zone when the file fails validation.

Variants

The component has two key states that define the primary visual:

• Empty — no file has been selected. The drop zone shows instructions (e.g., "Drag and drop or click to upload").
• Filled — a file has been selected. The file name is displayed along with a remove option.

Combined with the error flag, this gives four visual configurations:

States

• Default (empty) — the drop zone is idle, awaiting user input.
• Hover / drag-over — the drop zone highlights when the cursor hovers or a file is dragged over it.
• Focus — a visible focus ring appears when the drop zone is navigated via keyboard.
• Filled — a file has been selected and is displayed.
• Error — validation has failed; error styling and an error message are shown.
• Disabled — the component is non-interactive.

Placement & layout

The file upload component spans the full width of its form column. It should appear in the same vertical flow as other form fields, with consistent spacing above and below.

Place helper text (accepted formats, max file size) below the drop zone in the default state so the user has the information before they try to upload.

Accessibility

• The clickable drop zone must be focusable and activatable via keyboard (Tab to focus, Enter or Space to open the file picker).
• The associated <label> must be linked to the hidden <input type="file"> so screen readers announce what the field expects.
• Drag and drop is a progressive enhancement; the click-to-upload mechanism must always work as a fallback.
• Error messages must be associated with the field via aria-describedby so they are announced to screen reader users.
• On file selection, announce the selected file name to assistive technologies (e.g., via an aria-live region or by moving focus to the file item).

Related components

• Input — for text-based form fields.
• Notification — for communicating broader upload success or failure after a form is submitted.