(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.

Specs

Tokens

Structure

• Consists of a button that opens the system’s file picker dialog.
• Selected files are displayed in a list, with optional previews.
• Supports configuration for multiple file selection, default values, and local storage persistence.

(Configured in General Properties)

• displayName - Sets the display name of the component shown in the structure panel. For example, "Document Uploader" allows for easy identification of the component's purpose in the application structure, making it easier for developers to locate and work with this specific file upload component.

(Configured in Non-Visual Properties)

• dataField - Defines the field name that will be used when submitting form data. For example, setting to "documentAttachment" ensures the file data is submitted with this field name in the form data object, making it clear what the data represents on the server side.
• accept - Specifies which file types are accepted by the uploader. For example, ".pdf,.docx,image/*" restricts uploads to only PDF documents, Word documents, and all types of images, preventing users from selecting incompatible file types.
• controlsRequestType - Specifies how the field data is sent in HTTP requests: 'BODY', 'HEADER', or 'PATH'. For example, setting to "BODY" includes the file data in the request body, which is standard for most file upload implementations.

(Configured in Visual Properties)

• defaultValue - Sets the initial file data that will be used when the form is reset. For example, setting to a predefined file reference would pre-populate the uploader with an existing file when a form is first loaded or reset.
• saveInLocalStorage - Determines whether the component's uploaded files data is preserved in local storage between sessions. When enabled, file references persist between page reloads, improving user experience for complex forms that may take time to complete.

Styling

(Configured in Visual Properties)

• labelTranslations - Sets the button text displayed on the file upload button, with support for multiple languages. For example, {"en-US": "Upload Files", "de-DE": "Dateien hochladen"} ensures proper localization of the button text based on the user's language preferences.
• disabled - Controls whether the upload button can be interacted with by users. When set to true, the upload button appears grayed out and cannot be clicked, which is useful when file uploads should be temporarily disabled while preserving the component's visibility.
• hidePreview - Determines whether thumbnails or previews of uploaded files are displayed. When set to true, only file names are shown without visual previews, which is more appropriate for document uploads where previews may not be helpful or necessary.
• buttonSize - Sets the size of the upload button for better visual integration with your design. Options include "medium" (standard size), "large" (more prominent), and "extra_large" (maximum visibility). For example, setting to "large" makes the upload button more prominent on forms where file upload is a primary action.
• buttonType - Determines the visual style of the upload button. Options include "primary" (highlighted main action), "secondary" (alternative action), or "ghost" (minimal visual presence). For example, using "primary" for the main file uploader draws attention to this action, while "ghost" works well for optional file uploads.
• paddingClass - Configures spacing around the file upload component using CSS classes. For example, "p-4" adds medium padding on all sides of the component to improve visual spacing within its container.

Actions & Variants

(Configured in Visual Properties)

• readonly - Controls whether files can be uploaded by users. When set to true, the file selection interface is disabled but existing files are still displayed, which is useful for viewing previously uploaded files without allowing changes.
• hidden - Controls whether the component is visible in the form. When set to true, the component remains in the form structure but is not displayed, which is useful for conditional file upload capabilities based on other form values.

(Configured in Non-Visual Properties)

• multiple - Enables users to select and upload multiple files at once. When set to true, users can select multiple files in the file picker dialog, making it more efficient to upload several files at once rather than uploading them one by one.

(Configured in Events)

• events - Configures the events that the component can trigger and respond to:
• ON_VALUE_CHANGE - Triggered when files are added or removed. Can be used to perform actions based on file selection changes, such as enabling a submit button only when files are selected.
• ON_INIT_BASED_ON_USER_VIEW - Triggered specifically when the component initializes in user view mode rather than edit mode.
• ON_INIT - Triggered when the file upload component is initialized. Can be used to perform setup operations like fetching allowed file types from a configuration service.
• ON_DESTROY - Triggered when the component is removed from the DOM. Useful for cleanup operations and releasing resources.

Authorization

(Configured in Authorization)

• authorizationDisable - Specifies a policy set that determines when the component should be disabled based on user permissions. For example, setting to "readOnlyPolicy" will disable the file uploader for users who don't have content editing permissions according to the specified policy.
• visibilityPolicySetId - Determines the visibility of the component based on specified policy sets. For example, setting to "documentAccessPolicy" restricts the file uploader visibility to users with document management privileges.

Tests

(Configured in Testing Hooks)

• 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

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

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.