Dropzone

The default <input type="file"/> is just a quite boring button. That's why we present the <Dropzone/>component as an special input enhanced by the ability to allow users to drag and drop files there or choose files from a file dialog and also to validate an upload them.

The widget is useful for handling one

File

or a list of

Files

in one or more of these scenarios:

The file(s) must be chosen from a File Dialog or must be dragged and dropped into the widget
The file(s) must be validated or not. If validation is required, it can be done by taking into account a predefined set of allowed Common MIME Types; specifiying the max file size (in bytes) and/or the max amount of files.
The file(s) must be uploaded somewhere in the internet.

It's meant to be an improved version of the react-dropzone and dropzone packages.

Basic Dropzone

In this demo we set the <Dropzone/> with the minimum props that allows you to get your task done fast. These props are onChange and value.

Drop your files here

<Dropzone
  onChange={updateFiles}
  value={files}
>
   {files.map((file) => (
       <FileMosaic key={file.id} {...file} onDelete={removeFile} info/>
     ))}
</Dropzone>

FileMosaic

For completeness, these examples include <FileMosaic/> component for showing the files selected by the user with minimun props too. For further information of this component check out the FileMosaic page.

ExtFile

ExtFile type is explicity used in the Typescript example and is implicity used in the Javascript example for handling the metadata that makes possible the information exchange between components. For further information about this data type check out the ExtFile-API.

Validation

In this demo you can see how <Dropzone/> component covers the following features when it comes to validating files.

Accepting specific file types.
Accepting an specific number of files.
Accepting files with an specific size (in bytes).

Max file size: 28.00 KB, Files 0/2,

Drop your files here

<Dropzone
    onChange={updateFiles}
    value={files}
    accept="image/*"
    maxFileSize={28 * 1024}
    maxFiles={2}
     //cleanFiles
    actionButtons={{ position: "bottom", cleanButton: {} }}
>
   {files.map((file) => (
       <FileMosaic key={file.id} {...file} onDelete={removeFile} info/>
     ))}
</Dropzone>

Removing non valid Files

We call "clean" to the operation of removing non valid files. Apart from deleting them individually, there are some other ways in which you can remove all of them. You can try the following props in the <Dropzone/> component:

cleanFiles
: This will make dropzone header to display the "clean" icon which can trigger the "clean" operation.
actionButtons
: By setting this prop properly, a button will be visible and will trigger the "clean" operation (This is the way used in this demo).
autoClean
: By setting this prop, non valid files will be automatically discarted and will not be given in the onChange event.

Custom validation

You can also override the Dropzone validation operation by giving a custom validation function that must fit the following signature: validator?: (f: File) => ValidateFileResponse. Custom validator can work together with

maxFileSize

and

maxFiles

props.

Max file size: 28.00 KB, Files 0/2,

Drop your files here

Uploading

For uploading , the prop

uploadConfig

must be given. This prop recieves an object in which you can specify the HTTP method, the url, the headers and also extra data to be uploaded. The type definition for the prop mentioned can be found here.

Max file size: 28.00 MB, Files 0/2,

Drop your files here

<Dropzone
    onChange={updateFiles}
    value={files}
    accept={"image/*"}
    maxFileSize={28 * 1024*1024}
    maxFiles={2}
    actionButtons={{ position: "bottom", uploadButton: {}, abortButton: {} }}
    uploadConfig={{
        url: "https://www.myawsomeserver.com/upload",
        method: "POST",
        headers: {
            Authorization:
             "bearer HTIBI/IBYG/&GU&/GV%&G/&IC%&V/Ibi76bfh8g67gg68g67i6g7G&58768&/(&/(FR&G/&H%&/",
         },
        cleanOnUpload: true,
     }}
    onUploadFinish={handleFinishUpload}
    fakeUpload
>
   {files.map((file) => (
       <FileMosaic key={file.id} {...file} onDelete={removeFile} info preview/>
     ))}
</Dropzone>

Server response

For uploading files through files-ui, server must return the response with the structure of the

ServerResponse

type.

"fakeUpload"

By giving this prop, the <Dropzone/> component will simulate the upload operation by randomly setting the upload status and message on each uploadable

ExtFile

. It will also set a fake progress.

Upload config properties

Apart from the properties you can see in the example above, there are more of them that can make the upload process to behave differently.

autoUpload
: By setting this prop to true, the upload process will start automatically just after the user drops or selects files.
cleanOnUpload
: By setting this prop, you can control whether the upload process should "clean" the non valid files before uploading or not. By default this value is true.

More information about the uploadConfig type structure can be found here.

Dropzone with action buttons

If you need to display buttons that trigger the default events in the <Dropzone/> component, you can do it by adding the

actionButtons

prop. This will add buttons to the top or to the bottom of this component.

Dropzone with the
actionButtons.cleanButton
prop defined will display a button which triggers the clean process.
This button will be visible only when the "upload" process is not active.
Dropzone with the
actionButtons.deleteButton
prop defined will display a button which deletes all files.
this button will be visible only when the "upload" process is not active.
Dropzone with the
actionButtons.uploadButton
prop defined will display a button which starts the upload process. This button will not be visible during the "upload" process.
Dropzone with the
actionButtons.abortButton
prop defined will display a button which stops the upload process.
This button will be visible only during the "upload" process.

Drop your files here

<Dropzone
    onChange={updateFiles}
    value={files}
    autoClean
    uploadConfig={{ url: "https://www.myawsomeserver.com/upload" }}
    fakeUpload
    actionButtons={{
      position: "after",
      uploadButton: { style: { textTransform: "uppercase" } },
      abortButton: {},
      cleanButton: {},
      deleteButton: {},
     }}
>
   {files.map((file) => (
       <FileMosaic key={file.id} {...file} onDelete={removeFile} info/>
     ))}
</Dropzone>

Dropzone header config

You can use the

headerConfig

prop to define what will be displayed in the header.

Dropzone with the
headerConfig.customHeader
prop defined will display this prop replacing the entire default header.

By default all of these values are set to

true

Drop your files here

<Dropzone
    onChange={updateFiles}
    value={files}
    headerConfig={{
      customHeader: (
         <div style={{ display: "flex", justifyContent: "flex-end" }}>
           <button
            style={{ backgroundColor: "teal", color: "white" }}
            onClick={removeAllFiles}
           >
            delete files
           </button>
         </div>
       ),
     }}
>
   {files.map((file) => (
       <FileMosaic key={file.id} {...file} onDelete={removeFile} info/>
     ))}
</Dropzone>

HeaderConfig

There are more options that can be defined such as:

Dropzone with the
headerConfig.deleteFiles
prop set to
true
will display a delete button which triggers the delete process.
This button will be visible only when the "upload" process is not active.
Dropzone with the
headerConfig.cleanFiles
prop set to
true
will display a "clean" buton. This button will be visible only during the "upload" process.
button will be visible only when the "upload" process is not active.
Dropzone with the
headerConfig.uploadFiles
prop set to
true
will display a button which starts the upload process.
Dropzone with the
headerConfig.uploading
prop set to
true
will display a loading icon during the "upload" process.
Dropzone with the
headerConfig.maxFileSize
prop set to
true
will display the max file size label.
Dropzone with the
headerConfig.validFilesCount
prop set to
true
will display the current count of valid files.

By default all of these values are set to

true

. The complete type definition can be found here.

Dropzone footer config

You can use the

footerConfig

prop to define what will be displayed in the footer.

Dropzone with the
footerConfig.customMessage
prop defined will be considered the message to display in the footer.

Drop your files here

<Dropzone
  onChange={updateFiles}
  value={files}
  footerConfig={{ customMessage: "This is a custom message..." }}
>
   {files.map((file) => (
       <FileMosaic key={file.id} {...file} onDelete={removeFile} info/>
     ))}
</Dropzone>

FooterConfig

There are more options that can be defined such as:

Dropzone with the
footerConfig.allowedTypesLabel
prop set to
false
will hide the label that indicates the allowed file types. This label is normally hidden when the "upload" process is active.
Dropzone with the
footerConfig.uploadProgressMessage
prop set to
false
will not display the that indicates the current upload progress. This label is normally visible only during the "upload" process.
Dropzone with the
footerConfig.uploadResultMessage
prop set to
false
will not display a label that indicates the final result of the upload progress will not be shown. This label is normally visible for 2 seconds just after the "upload" process finishes.
Dropzone with the
footerConfig.noMissingFilesLabel
prop set to
false
will not display a label that indicates that there are not files missing to upload.
Dropzone with the
footerConfig.style
prop defined will override the styles associated to the footer component.

By default all of these values are set to

true

.
The complete type definition can be found here.

Styling Dropzone

You can use change the look and feel of the Dropzone component

Dropzone with the
color
prop defined will use this color for border, drop layer, font color and ripple.
Dropzone with the
minHeight
prop defined will use this value to define the minimum height of the component.
Dropzone with the
background
prop defined will use this value for the background. You can set nice gradients or even a background image.

Drop your files here

<Dropzone color="#6200EE">{/** files */}</Dropzone>
<Dropzone
    minHeight="120px"
    header={false}
    footer={false}
>
   {/** files */}
</Dropzone>
<Dropzone
    background="radial-gradient(circle at 18.7% 37.8%, rgb(250, 250, 250) 0%, rgb(225, 234, 238) 90%);"
>
   {/** files */}
</Dropzone>

Label

You can specify a fixed label for <Dropzone/> component to display when there isn't any files.

Drop your files here

Files ui ❤️

<Dropzone style={{ width: "300px" }}>{/**Files */}</Dropzone>
<Dropzone
  style={{ width: "300px" }}
  label={"Files ui ❤️"}
>
   {/**Files */}
</Dropzone>

Ripple

According to Material Design, the Ripple component provides a radial action in the form of a visual ripple expanding outward from the user's touch. Ripple is a visual form of feedback for touch events providing users a clear signal that an element is being touched. In this component, a ripple is displayed after 2 user actions:

When user clicks or touches the component.
Just after user dropped files.

For disabling the ripple effect you can set the

disableRipple

prop to true.

ripple enabled

ripple disabled

<Dropzone style={{ width: "300px" }}>{"ripple enabled"}</Dropzone>
<Dropzone style={{ width: "300px" }} disableRipple>
   {"ripple disabled"}
</Dropzone>

Disabled Dropzone

According to Material Design a disabled state communicates when a component or element isn’t interactive, and should be deemphasized in a UI.

disabled

prop to true.

Drop your files here

Dropzone is disabled

<Dropzone style={{ width: "300px" }}>{/**Files */}</Dropzone>
<Dropzone style={{ width: "300px" }} disabled>
   {"Dropzone is disabled"}
   {/**Files */}
</Dropzone>

Clickable Dropzone

Dropzone with the

clickable

prop set to false will not open the file dialog to select files when user clicks the component.

Drop your files here

<Dropzone style={{ width: "300px" }}>{/**Files */}</Dropzone>
<Dropzone style={{ width: "300px" }} clickable={false}>
   {/**Files */}
</Dropzone>

Drop Layer

Dropzone with the

dropOnLayer

prop set to false will not perform the drop operation in a layer that covers the complete component container.
In this demo try to drag and drop files in both dropzones to see the difference.

Drop your files here

<Dropzone style={{ width: "300px" }}>{/**Files */}</Dropzone>
<Dropzone style={{ width: "300px" }} dropOnLayer={false}>
   {/**Files */}
</Dropzone>

Add or replace files

There are 2 different behaviours when user selects or drops new files:

Dropzone with the behaviour set to
"add"
will add the new files to the current array of ExtFiles.
Dropzone with the behaviour set to
"replace"
will replace the current array of ExtFiles with the new ones.

In this demo try to select or drop files more than once on each dropzone to see the difference.

Dropzone with behaviour=add

Dropzone with behaviour=replace

<Dropzone
  style={{ width: "min(100% , 420px)" }}
  onChange={updateFilesAdd}
  value={filesAdd}
  label="Dropzone with behaviour=add"
  behaviour={"add"}
>
   {filesAdd.length > 0 &&
    filesAdd.map((file) => (
       <FileMosaic
        key={file.id}
         {...file}
        onDelete={removeFileAdd}
        info
        preview
       />
     ))}
</Dropzone>
<Dropzone
  style={{ width: "min(100% , 420px)" }}
  onChange={updateFilesReplace}
  value={filesReplace}
  label="Dropzone with behaviour=replace"
  behaviour={"replace"}
>
   {filesReplace.length > 0 &&
    filesReplace.map((file) => (
       <FileMosaic
        key={file.id}
         {...file}
        onDelete={removeFileReplace}
        info
        preview
       />
     ))}
</Dropzone>

Localization

<Dropzone/> component uses the

localization

prop in the validation and the upload process for setting status and messages according to the language that this prop refers to.
The localization demo for this component can be found in the localization page.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<Dropzone />
<FileMosaic />