Versions Compared

Old Version 2

changes.mady.by.user GE-DevDoc-Bot

Saved on

compared with

New Version 3

changes.mady.by.user GE-DevDoc-Bot

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

File Upload

Link to Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11528-202526&t=iosNC2AkSTGs5lMh-1

Overview

  • The Dynamic File Upload Component is a flexible form control for uploading files.
  • Developers can customize appearance, behavior, and file restrictions.
  • It is useful for document submission, attachment uploads, or profile picture uploads.
  • It supports workflows that require file input from users.

...

  • dataTestId - Sets the testing hook ID for automated testing. For example, setting to "invoice-file-upload" allows test scripts to reliably locate this component for automated testing of file upload functionality.
  • enableAsHotspot - Enables the component as a guided tour hotspot. When enabled, the file upload component can be highlighted during onboarding or tutorial flows to explain its functionality to new users.
  • guidedTourHotSpotTitle - Sets the title for the guided tour hotspot, supporting translations. For example, {"en-US": "Upload Your Documents Here", "de-DE": "Laden Sie Ihre Dokumente hier hoch"} provides instructional text during guided tours.
  • guidedTourHotSpotDescription - Sets the description for the guided tour hotspot, supporting translations. For example, {"en-US": "Click to upload PDFs, Word documents, or images", "de-DE": "Klicken Sie hier, um PDFs, Word-Dokumente oder Bilder hochzuladen"} provides detailed instructions during guided tours.

Guidelines

  • File Upload Validation - File uploads are included as part of individual validations. These are handled separately from standard validations to ensure correct data handling and error management.

Accessibility

...

Usage

  • Use for collecting documents, images, or other files, setting the accepted types via accept (e.g., .pdf,.docx,image/*) to prevent incompatible selections.
  • Allow bulk submission with multiple: true when users commonly attach several files at once.
  • Show existing uploads without allowing edits by turning on readonly; use defaultValue to pre-populate known file references on load/reset.
  • Persist selected files across reloads for long tasks by enabling saveInLocalStorage.

Sizing & Layout

  • Match prominence to task: set buttonSize (medium, large, extra_large) and buttonType (primary, secondary, ghost) for clear hierarchy.
  • Reduce visual noise for document-heavy flows by hiding thumbnails with hidePreview: true.
  • Create breathing room around the control with paddingClass (e.g., p-4) to maintain readable spacing.

States & Feedback

  • Prevent interaction during blocked steps by toggling disabled: true; present files without edits using readonly.
  • Pre-populated vs. empty are distinct states managed by defaultValue.

Data-Driven / Conditional Behavior

  • Gate file types with accept; prefer broader wildcards (e.g., image/*) only when necessary to avoid rapid rule changes.
  • Use controlsRequestType (BODY, HEADER, PATH) to align upload placement with backend expectations.

Visibility & Authorization

  • Hide from unauthorized users via visibilityPolicySetId; keep visible but inactive where awareness is needed using authorizationDisable or disabled.

Content & Localization

  • Provide clear, localized call-to-action text with labelTranslations (e.g., “Upload files”).
  • Name the submission key explicitly using dataField so the backend receives a predictable field name.
  • Improve onboarding with translated hotspot copy via enableAsHotspot, guidedTourHotSpotTitle, and guidedTourHotSpotDescription.

Dos & Don’ts

DoDon’t
Restrict selection with precise accept values to prevent unsupported files.Allow any file type and rely on error handling later.
Enable multiple only when users truly need to attach several files.Always allow multiple files even for single-document tasks.
Use readonly to show existing uploads without edits.Simulate read-only by disabling and hiding files.
Set buttonSize/buttonType to reflect action priority.Depend on default styling for critical uploads.
Initialize defaults or rules at ON_INIT for stability.Recompute accept or reset multiple repeatedly during use.
Hide for restricted roles via visibilityPolicySetId.Show the control and rely solely on server errors to block access.
Persist selections with saveInLocalStorage for long forms.Force users to reselect files after reloads when progress should persist.
Use ON_VALUE_CHANGE to trigger validation or enable-submit logic.Wait until final submit to detect missing/invalid files.

Accessibility

  • Provide localized, concise button text via labelTranslations so assistive tech announces clear actions.
  • Keep file requirements transparent: encode constraints in accept and reflect them in the labelTranslations text where needed.
  • Prevent non-functional interaction with disabled or readonly until the control is ready.
  • Reduce cognitive load by disabling thumbnails where unnecessary with hidePreview.
  • Avoid color-only meaning; communicate state with disabled/readonly and clear labelTranslations.
  • Increase target size when necessary using buttonSize and add space with paddingClass.