useDragAndDropUpload

useDragAndDropUpload is a hook that provides you with everything you need to allow the user to upload files by drag and dropping them on an element. It relies on the UploadManager/UploadTask API. The older FileUploader class is still supported but considered legacy.

Options object

The hook takes a single object with options as the only parameter. The possible values are:

Name	Type	Optional	Description
dataObject	DataObject	no	The data object to upload the files
fields	Record<string, any>	yes	If you need to set other fields on the new record, you can set them in this object. If you are uploading to a blog field, and you set a PrimKey in this object, the file will be uploaded to the existing record matching the primkey instead of creating a new record.
blobField	string	yes	To store the file in a blob field instead of the filestore, set the name of the field here
refreshOnUpload	boolean	yes	Whether the data object should be refreshed whenever a file is uploaded (default true)
onUploaded	(status: UploadStatus) => void	yes	A function that will be called whenever a new file is uploaded
validateFile	(item: DataTransferItem) => boolean	yes	If you need to validate the file (for example check if it is an image), you can pass a function that takes a DataTransferItem and returns a boolean here. If the method returns false, the file will not be uploaded

Return value

Name	Type	Description
dragOver	boolean	Whether the user is currently dragging an item over the element
dragProps	Drag'n'drop event handlers	Event handlers that should be passed to the drop container (onDragEnter, onDragLeave, onDragOver and onDrop)
removeStatus	(index: number) => void	Method to remove a status item, typicall if there is an error
upload	(files: FileList | File[], fields?: Record<string, any>) => void	Method to manually upload files, typically from a file input
status	UploadStatus[] (see below)	Array of status objects for files currently uploading

UploadStatus

Name	Type	Description
error	string | null	If the upload failed, this will contain the error message
complete	boolean	Whether the upload is completed
name	string	Name of the file being uploaded
progress	{ loaded: number; total: number}	The progress of the upload
task	UploadTask	A reference to the underlying upload task
index	number	Index of the current status. Can be used to remove error statuses with removeStatus
size	number	Size of the file being uploaded

Usage

In this example we let the user drop files on an element, but also allow them to browse by clicking the file input label. We also check that the file is an image, and stop the upload if not.

function MyLogoUploadComponent() {
  let { dragOver, dragProps, upload, status } = useDragAndDropUpload({
    dataObject: dsCustomerLogo,
    validateFile(file) {
      if (!file.type.startsWith("image/")) {
        alert(getLocalizedString("Only images can be uploaded"));
        return false;
      }
      return true;
    },
  });

  let inputRef = useRef<HTMLInputElement>(null);

  async function handleFileChanged() {
    if (!inputRef.current) return;
    if (inputRef.current.files && inputRef.current.files.length > 0) {
      let file = inputRef.current.files[0];
      upload([file]);
      dsCustomerLogo.refreshDataSource();
    }
  }

  let isError = !!status[0]?.error;
  let isUploading = status.length > 0;

  return (
    <div
      className={clsx(dragOver && "ob-drag--over")}
      {...dragProps}
    >
      <input
        className="sr-only"
        type="file"
        ref={inputRef}
        id="new-logo-upload"
        onChange={handleFileChanged}
      />
      {isError && (
        <Alert severity="error" sx={{ mb: 2 }}>
          <AlertTitle>{getLocalizedString("Upload failed")}</AlertTitle>{" "}
          {status[0].error}
        </Alert>
      )}
      {!isUploading && !isError && (
        <>
          <Typography variant="body"
            component="label"
            htmlFor="new-logo-upload"
            variant="contained"
          >
            {getLocalizedString("Select logo")}
          </Button>
          {getLocalizedString("or drag and drop a file here")}
        </>
      )}
      {isUploading && (
        <Box display="flex" gap={2}>
          <Typography variant="body1">{status[0].name}</Body>
          <LinearProgress
            variant="determinate"
            value={(status[0].progress.loaded / status[0].progress.total) * 100}
          />
        </Box>
      )}
    </div>
  );
}

API

import { DragEventHandler } from "react";
import { DataObject, UploadTask } from "@olenbetong/appframe-data";

export declare type UploadStatus = {
  error: string | null;
  complete: boolean;
  name: string;
  progress: {
    loaded: number;
    total: number;
  };
  task: UploadTask;
  index: number;
  size: number;
};

export declare type DragAndDropData<T = any> = {
  dragOver: boolean;
  dragProps: {
    onDragEnter: DragEventHandler<any>;
    onDragLeave: DragEventHandler<any>;
    onDragOver: DragEventHandler<any>;
    onDrop: DragEventHandler<any>;
  };
  removeStatus: (index: number) => void;
  upload: (files: FileList | File[], fields?: Record<string, any>) => void;
  status: UploadStatus[];
};

/**
 * Returns status and drag and drop props for use on a HTML element. Files dropped on the element
 * will be automatically uploaded to the data object.
 *
 * @param dataObject The data object to upload to
 * @returns
 */
export declare function useDragAndDropUpload<T = any>({
  dataObject,
  fields: hookFields,
  blobField,
  validateFile,
}: {
  dataObject: DataObject<T>;
  fields?: Record<string, any>;
  blobField?: string;
  validateFile?: (file: DataTransferItem) => boolean;
}): DragAndDropData<T>;