Bauhaus Design System

FileUpload ​

Molecule

This component lets users upload files by dragging and dropping them into an area, or by browsing files on their native OS from a link.

Playground ​

ModelValues

For more information on ModelValues please have a look to the Vue's Data Binding section.

ts
const files = defineModel<(InputFile | FileRejectReason)[]>({ required: true });

Properties ​

ts
export type FileUploadProps =
  & Omit<FormLabelOptionalProps, 'disabled' | 'labelPosition' | 'labelCategory'>
  & TooltipProps
  & {
    modelValue: InputFile[];
    dropzoneOptions?: Partial<FileUploadOptions>;
    onFileDelete?: (file: InputFile, index: number) => void;
    actionText?: string;
    hideLabel?: boolean;
    hideFileCount?: boolean;
    onDragInstructions?: string;
    useFileTypeHint?: boolean;
    fileTypeInstructions?: string;
    disabled?: boolean;
    helpText?: HelpTextProps['text'];
    validation?: HelpTextProps['category'];
  };

  type FileHandler = (evt: Event) => void;

  export interface FileUploadOptions {
    accept: string[];
    getFilesFromEvent: (evt: Event | any) => Promise<InputFile[]>;
    // in MB
    maxSize: number;
    minSize: number;
    multiple: boolean;
    maxFiles: number;
    onDragEnter: FileHandler;
    onDragLeave: FileHandler;
    onDragOver: FileHandler;
    onDrop: (acceptedFiles: any[], rejectReasons: FileRejectReason[], event: Event) => void;
    onDropAccepted: (acceptedFiles: InputFile[], event: Event) => void;
    onDropRejected: (rejectReasons: FileRejectReason[], event: Event) => void;
    onFileDialogCancel: () => void;
    preventDropOnDocument: boolean;
    noClick: boolean;
    noKeyboard: boolean;
    noDrag: boolean;
    noDragEventsBubbling: boolean;
}
ts
export type FormLabelCategory = "compact" | "default";
export type FormLabelPosition = "labelLeading" | "labelTrailing" | "labelAbove";

export interface FormLabelProps extends TooltipProps {
  label?: string;
  tooltip?: string;
  labelCategory: FormLabelCategory;
  labelPosition: FormLabelPosition,
  disabled?: boolean;
  required?: boolean;
  clickableLabel?: boolean;
}
ts
export type TooltipPosition = 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center';

export interface TooltipProps {
  tooltip?: string;
  tooltipPosition?: TooltipPosition;
  tooltipLines?: number;
}

Developer Notes ​

NOTE

Delete File Event (@deleteFile): Triggered when user clicks the delete icon on a file. The event sends the file and its current index within the files modelValue as payload.

Usage Example ​

vue
<script setup lang='ts'>
type Props = FileUploadProps;

const pg = reactive({
  required: false,
  useFileTypeHint: true as NonNullable<Props['useFileTypeHint']>,
  helpText: 'Help Text' as Props['helpText'],
  validation: 'info' as Props['validation'],
  label: 'Upload Files'
  hideLabel: false,
  tooltip: "",
  tooltipPosition: 'top-center' as NonNullable<Props['tooltipPosition']>,
  disabled: false,
});

const files: InputFile[] = $ref([]);

// here you'd setup the actual API calls to upload files
const onDrop = (acceptedFiles: InputFile[], rejectReasons: FileRejectReason[]) => {
  console.log('acceptedFiles', acceptedFiles);
  console.log('rejectReasons', rejectReasons);
};

// by default does not need to be reactive when no change during runtime
const dropzoneOptions = reactive({
  onDrop,
  maxSize: 3 * 1024 * 1024, // maxSize is in bytes, this calculates 3MB
  maxFiles: 10,
  accept: ['application/pdf'],
  multiple: true,
  disabled: false
});

// this would handle the actual API call to delete a file
// make sure to distinguish between the different file states, though
const onDeleteFile = (file: InputFile | FileRejectReason, index: number) => {
  files.splice(index, 1);
};
</script>

<template>
  <FileUpload
    v-model="files"
    v-bind="{
      ...pg,
    }"
    :dropzoneOptions="dropzoneOptions"
    @deleteFile="onDeleteFile"
  >
  </FileUpload>
</template>

Tokens ​

SCSS Variable
Value
$fileUpload-color
--color-grey-40
$fileUpload-color-disabled
--color-grey-70
$fileUpload-color-error
--color-red-50
$fileUpload-typeInstructions-color
--color-grey-54
$fileUpload-icon-color
--bds-brand-primary-color
$fileUpload-icon-color-disabled
--bds-brand-primary-color-locked
$fileUpload-dropzone-border-color
--color-grey-54
$fileUpload-dropzone-border-color-dragged
--bds-brand-primary-color
$fileUpload-dropzone-bgColor-dragged
--color-grey-90
$fileUpload-fileCount-color
--color-grey-54
$fileUpload-dropzone-padding
--gutter-m
$fileUpload-dropzone-border-radius
--gutter-m
$fileUpload-file-status-color-accepted
--bds-brand-primary-color
$fileUpload-file-status-color-rejected
--color-red-50
$fileUpload-file-status-color-pending
--color-grey-70
$fileUpload-file-bgColor
--color-grey-90
$fileUpload-file-bgColor-hover
--color-grey-86
$fileUpload-file-color--disabled
--bds-brand-primary-color-locked
$fileUpload-file-color-text-error--disabled
--color-red-70

Anatomy ​

  1. Form Label (compact) - default reads “Upload files:” but can be customized. Also can be hidden.
  2. Help Text - specifies any limits of the upload, such as number of files or maximum file size. Also can be hidden.
  3. Link - user can click to open native OS browser to navigate to files for upload. Ensure link text is all on one line.
  4. Drag Area - the area where a user can drag a file and drop it to trigger upload. Changes states when a file is dragged over the area.
  5. File - subcomponent, representing each file that has been uploaded. This component has a hover and locked state. This component has 4 different variants representing the individual file upload’s status: Complete, Error File, Error Size and Error Both. When there is an error the file name text, and/or file size text turns red when the error relates to the file type and/or size respectively.
  6. File Count - counts how many files have been successfully uploaded and shows the limit of how many files can be uploaded. When the limit has been reached the Drag Area locks. Also can be hidden.
  7. Error Text (Help Text) - indicates to the user that one or more files cannot be uploaded
States
  • Default
  • Dragged file - when a file is dragged over the drop area
  • Disabled - when uploading is not available or an error has occurred
Variants
Files
  • After files are uploaded, they appear below the drag Area
  • Show or hide sample files to demonstrate this functionality
Label

Show or hide Label

Help Text

Show or hide Help Text

File Count

Show or hide File Count