Dropzone UI
The best, most complete and easy to use, React file upload library.
Github :D
Key Features
-
✅ File validation: Validate files before uploading. -
🎨 File Image previews: See a thumbnail preview -
🖼️ Full screen image previews: Add more interacion with a full screen preview of images -
🎥 Full screen video previews. Play the video before uploading. -
👀 status visualization: validation and upload status is shown on a Tooltip or on Info Layer. -
✈️ File upload: Upload valid files to a server. -
🎭 Out of the box design and style. -
🍰 Easy to use. Probably, this is the killer feature you are looking for in a package.
Main Content
Ordered by use:
Sample result:
On Drag, Drop, Upload and full screen preview. (also changing view mode from grid to list).
Code generator
Want to generate the code that fits your needs? Just interact with the code generator here.
Requirement
@dropzone-ui/react is based on React Hooks. It requires react v16.8+.
@dropzone-ui/react uses axios for uploading files. It requires axios v0.24.0+.
Installation
@dropzone-ui/react is available as an npm package.
For uploading files, peer dependency axios must be also installed together with dropzone-ui.
// with npm
npm i @dropzone-ui/react axios
// with yarn
yarn add @dropzone-ui/react axios
Usage and examples
Here is a quick example to get you started, it's all you need:
import * as React from "react";
import ReactDOM from "react-dom";
import { Dropzone, FileItem } from "@dropzone-ui/react";
Function App() {
const [files, setFiles] = React.useState([]);
const updateFiles = (incommingFiles) => {
setFiles(incommingFiles);
};
return (
<Dropzone onChange={updateFiles} value={files}>
{files.map((file) => (
<FileItem {...file} preview />
))}
</Dropzone>
);
}
ReactDOM.render(<App />, document.querySelector("#app"));
Yes, it's really all you need to get started as you can see in these live and interactive demos:
| Name | Codesandbox link |
|---|---|
| Dropzone Basic example |  |
| Dropzone Complete example | |
| File item props | |
VideoPreview  |
|
FileItem alwaysActive Prop |
|
FileItem resultOnTooltip Prop |
|
| FileItem with no image preview | |
| InputFileButton & FileItemContainer | |
localización: multilanguage example |
|
File Item imageUrl and synthetic files |
|
| Default previews extensive list | |
| headerClassName & footerClassName | |
Uploading
Dropzone-ui provides a way to upload files to a server. However, in case you want to make your own upload function, you can take the files that Dropzone onChange event returns.
For uploading files through dropzone-ui, you should follow at least this guidelines:
- Server Endpoint should get the file from
req.files.file. - Server Response should follow the
DropzoneUIResponsestructure for returning a response.
Server example
Bellow, there is an example built in Express.js wich you can use to create your own server side implementation. Other languages implementations are in construction.
The complete code can be found here.
const express = require("express");
const fileUpload = require("express-fileupload");
// ... some code
app.post("/upload-my-file", async (req, res) => {
try {
if (!req.files) {
res.send({
success: false,
message: "There was no file found in request",
payload: {},
});
} else {
//Use the name of the input field (i.e. "file") to retrieve the uploaded file
let file = req.files.file;
//Use the mv() method to place the file in upload directory (i.e. "uploads")
file.mv("./uploads/" + file.name);
//send response
res.send({
success: true,
message: "File was uploaded successfuly",
payload: {
name: file.name,
mimetype: file.mimetype,
size: file.size,
path: "/files/uploads/",
url: "https://my-ftp-server.com/bjYJGFYgjfVGHVb",
},
});
}
} catch (err) {
res.status(500).send({
status: false,
message: "Unexpected problem",
payload: {},
});
}
});
Localization
Dropzone-ui is available in different languages. So far, we only support English, Spanish, French and Portuguese. In next releases this list will be increased.
| Language | Code | Example |
|---|---|---|
| English |
EN-en |
localization="EN-en" |
| Spanish |
ES-es |
localization="ES-es" |
| Fench |
FR-fr |
localization="FR-fr" |
| Italian |
IT-it |
localization="IT-it" |
| Portuguese |
PT-pt |
localization="PT-pt" |
| Russian |
RU-ru |
localization="RU-ru" |
| Chinese(simplified) |
ZH-cn |
localization="ZH-cn" |
| Chinese(traditional) |
ZH-hk |
localization="ZH-hk" |
Dropzone UI react Components API
- < Dropzone />
- < FileItem />
- < FullScreenPreview />
- < VideoPreview />
- < FileItemContainer />
- < InputButton />
- Special Types
Dropzone API
Props
| Name | Type | Default | Description |
|---|---|---|---|
| accept | string |
undefined |
The accept attribute value is a string that defines the file types the Dropzone should accept. This string is a comma-separated list of unique file type specifiers, wich is compared with the file attributes in order to determine whether that file is valid or not: "image/*, application/pdf, .psd". More info on MDN . |
| behaviour | "add" | "replace" |
"add" |
The behaviour on drop files. "add" option will make Dropzone to add files to the current file list. "replace" option will make Dropzone to replace the current list of files |
| children | node |
true |
The content of the component. Normally a list of FileItem components or a label |
| clickable | boolean |
true |
If true, the dropzone component itself will be clickable |
| config | Object | { headers: { "content-type": "multipart/form-data;", }, } | Extra configuration for uploading, normally an object with headers or bearer token- |
| disableScroll |
boolean |
undefined |
if present or true, removes scrolls and sets the Dropzone content (FileItemContainer) in a grid view. It also disables maxHeight prop. Only minHeight prop will work. This feature was added to work together with resultOnTooltip prop of FileItem. If not present or false , FileItemContainer will set csss property "overflow" as "auto". |
| fakeUploading | boolean |
undefined |
If true, this flag will make dropzone to simulate a server upload. Use only in development. |
| footer | boolean |
true |
if true, shows the dropzone footer |
| footerClassName | string |
undefined |
if given, css styles for fotter will be overriden.footer |
| header | boolean |
true |
if true, shows the dropzone header |
| headerClassName | string |
undefined |
if given, css styles for header will be overriden. |
| label | string |
"Drop your files here" | Label to place when no files selected |
| localization | "EN-en" | "ES-es" | "FR-fr" | "PT-pt"| "RU-ru"| "ZH-cn"| "ZH-hk" |
"EN-en" |
The language to present labels. So far, only English, Portuguese, French,Russian, Chinese (simplifyed and traditional) and Spanish are suported. |
| method | "POST" | "PUT" | "PATCH" |
"POST" |
The method for uploading. |
| maxFiles | number |
undefined |
Max number of files to be accepted. If the value is 1, click event dialog will allow just a select a single file. (multiple prop on input tag will be false). If not set, vlidation will not consider a max amount of files and user will be allowed to drop or select Infinity files. |
| maxFileSize | number |
undefined |
max file size allowed in bytes. if not preent, will not be considered on validating the file |
| minHeight | string |
"280px" | The min height of the container in string format. e.g. '50vh' , '20%', '40em', '1rem' . This not consider the space for Footer and Header. |
| maxHeight | string |
"450px" | The max height of the container in string format. e.g. '50vh' , '20%', '40em', '1rem'. This not consider the space for Footer and Header. |
| onChange | (files: FileValidated[] ) => void |
undefined |
Probably one of the most important methods. The onChange event occurs when the value of the file list is changed. Returns as first paramater a list of FileValidated . This event is also triggered when upload starts and when upload finishes for each file in order to update the props on very FIleItem |
| onChangeView | Function |
undefined |
Event that ocurs when view mode has changed. First parameter is the current view mode. |
| onDrop | (filesDropped: FileValidated[])=> void |
undefined |
The onDrop event occurs when files are dropped indide the Dropzone or selected from file dialog. Normally used for retrieving the new files dropped as a list of FileValidated |
| onUploadStart | (files: FileValidated[]) => void |
undefined |
This event is triggered when upload process starts. Returns as first parameter the list of FileValidated that will be uploaded. Unlike Onchange, onUploadStart will only return a list of files thta are candidates to be uploaded, in case they are valid or upload status is "error" |
| onUploadFinish | onUploadFinish?: ( responses: FileDuiResponse[] ) => void; |
undefined |
This event returns as first aparameter the list of responses for each file after upload process. Responses are instances of FileDuiResponse. |
| uploadOnDrop | boolean |
false |
If true, onDrop event will return the list of files, but also will upload the files if url was set, and also config |
| url | string |
undefined |
The url endpoint to upload the files. Server response must match DropzoneUIResponse structure |
| validator | (f: File) => CustomValidateFileResponse |
undefined |
Must be a function that recieves as first parameter a File Object instance and must return a CustomValidateFileResponse object with 2 fields: valid (boolean value) and errors a string array of errors. This function will be used instead of the default validator. |
| view | "grid" | "list" |
"grid" |
grid will display files in a grid layout. list will display files in a horizontal list. Convenient for saving space in page. If not given, Dropzone component will show "change view" button. If view is given, it´ll be hidden. |
| value | FIleValidated[] |
[ ] | The current list of Files |
FileItem API
Props
| Name | Type | Default | Description |
|---|---|---|---|
| alwaysActive |
boolean |
false |
Flag that makes all buttons visible. If false, the buttons and info will be visible on hover |
| file | File |
undefined |
The actual File object instance |
| errors | string[] |
undefined |
The list of errors according to the validation criteria or custom validation function given. |
| elevation |
"1" | "2" | "3" | "4" | 1 | 2 | 3 | 4 | false |
undefined |
Shadow depth for the FileItem container. |
| hd | boolean |
undefined |
If present, preview on full screen will be presented in the real image resolution |
| id | string | number |
undefined |
identifier for the file |
| info | boolean |
false |
If present, the info layer and the info button will ve visible |
| imageUrl | string |
undefined |
A string base64 representation or web url of the image that will be set to the "src" prop of an <img/> tag <img src={imageUrl} />. If given, FileItem componnet will use this image instead of reading the image file. |
| localization | "EN-en" | "ES-es" | "FR-fr" | "PT-pt"| "RU-ru"| "ZH-cn"| "ZH-hk" |
"EN-en" |
The language to present labels. So far, only English, Portuguese, French,Russian, Chinese (simplifyed and traditional) and Spanish are suported. |
| onDelete | (id: number | string | undefined) => void |
undefined |
This event is triggered when close button is pressed or clicked. Returns as first parameter the if of the corresponding FileItem . If not given, "delete" button will not be visible. |
| onSee | Function |
undefined |
This event is triggered when "see" button is pressed or clicked. Returns as first parameter the image url in string format. Normally used in FullScreenPeview component. If hd present, will return the image url in the real quality. Otherwise, will return a minimized image with less resolution in order to save memory. |
| onWatch |
Function |
undefined |
This event is triggered when "play" button is pressed or clicked. Returns as first parameter the video file object. Normally used in VideoPreview component. |
| preview | boolean |
false |
If present, and if onSee present, "see" button will be visible and on click will trigger onSee function |
| resultOnTooltip |
boolean |
undefined |
Where to display result of validation: on InfoLayer or in Tooltip when user hovers the FileItem. |
| uploadMessage | string |
undefined |
The message to display when server responds. The server response should follow the structure of an instance of DropzoneUIResponse |
| uploadStatus | undefined | "uploading" | "success" | "error" |
undefined |
The status of the upload process |
| valid | boolean |
false |
whether to show a "valid" or "rejected" message ("valid", "denied"). By default valid is false (if not present, it's false too)This value will affect preview behaviour. If not valid, the preview will not be shown, nor the view button even when onSee and preview props are present. The functionality to allow to show preview despite of a not valid image file, is a feature that will be added in future releases. |
FullScreenPreview API
Props
| Name | Type | Default | Description |
|---|---|---|---|
| imgSource | string |
undefined |
The url string representation of the image |
| onClose | Function |
undefined |
A function that describes the close behaviour |
| openImage | boolean |
false |
Flag that indicates whether to open the image preview or close it |
VideoPreview API
Props
| Name | Type | Default | Description |
|---|---|---|---|
| videoSource | string |
undefined |
The video source in string format or File object. When a File object is given VideoPreview component will check if video type is included in the supported formats. (video/mp4, video/ogg, video/webm). Normally used with FileItem component when returns this value in onWatch handler. |
| onClose | Function |
undefined |
A function that describes the close behaviour |
| openVideo | boolean |
undefined |
Flag that indicates whether to open the video preview or close it |
| autoplay | boolean |
undefined |
Flag that indicates whether to play automatically the video or not. |
| controls | boolean |
undefined |
Flag that indicates whether to display the controls in the video player or not. |
FileItemContainer API
Props
| Name | Type | Default | Description |
|---|---|---|---|
| children | node |
true |
The content of he component. Normally a list of FileItem. By default Dropzone component already uses this component for containing the FileItem list children. |
| view | "grid" | "list" |
"grid" |
grid will display files in a grid layout. list will display files in a horizontal list. Convenient for saving space in page. |
| disableScroll |
boolean |
undefined |
if present or true, removes scrolls and sets the FileItemContainer in a grid view. It also disables maxHeight prop. Only minHeight prop will work. This feature was added to work together with resultOnTooltip prop of FileItem. |
InputButton API
Props
| Name | Type | Default | Description |
|---|---|---|---|
| accept | string |
undefined |
The accept attribute value is a string that defines the file types the InputButton should accept. This string is a comma-separated list of unique file type specifiers, wich is compared with the file attributes in order to determine whether that file is valid or not: "image/*, application/pdf, .psd". More info on MDN . |
| color | string |
"#071e25" |
The main color for the button. (e.g. "#FFFFFF", "rgb(255,12,45)") |
| disabled | boolean |
false |
whether the button will be disabled or not |
| id | string |
undefined |
the id of the component |
| label | string |
"Browse ..." | If given, this label will be showed inside the button |
| maxFileSize | number |
undefined |
max file size allowed in bytes |
| multiple | boolean |
false |
whether to accept multiple files or not |
| onChange | Function |
undefined |
What to do after selecting the files. Returns the File[] as first parameter |
| style | React.CSSProperties |
{} | the in-line style object |
| text | "uppercase" | "capitalize" | "lowercase" | "none" |
"capitalize" |
The text transform for the text inside the button label |
| textColor | string |
"white" | The font color in case variant is "contained" |
| validator | (f: File) => CustomValidateFileResponse |
undefined |
Must be a function that recieves as first parameter a File Object instance and must return a CustomValidateFileResponse object with 2 fields: valid (boolean value) and errors a string array of errors. This function will be used instead of the default validator. |
| variant | "text" | "outlined" | "contained" |
"contained" |
The variant of the button |
Special Types Api
FileValidated
This is the file structure that is used in onChange event from Dropzone. This object contains all the required props to work dynamically with FileItem component.
export enum UPLOADSTATUS {
uploading = "uploading",
success = "success",
error = "error"
}
export interface FileValidated {
file: File;
valid: boolean;
id: number| string | undefined;
errors?: string[];
uploadMessage?: string;
uploadStatus?: undefined | UPLOADSTATUS;
}
FileDuiResponse
This is the object structure for responses thatcomes from server when Dropzone onUploadFinish event is triggeed. This event returns an array of FileDuiResponse objects
export interface FileDuiResponse {
id: number | string | undefined;
serverResponse: DropzoneUIResponse | {};
}
DropzoneUIResponse
This is the response structure for each file that server must send when Dropzone perfoms the upload process.
export interface DropzoneUIResponse {
status: boolean;
message: string;
payload: any;
}
UploadPromiseAxiosResponse
This is the response object after uploading each file.
export interface UploadPromiseAxiosResponse {
serverResponse: FileDuiResponse;
uploadedFile: FileValidated;
}
CustomValidateFileResponse
This is the response structure for each file that server must send when Dropzone performs the upload process.
export interface CustomValidateFileResponse {
valid: boolean;
errors?: string[];
}
Supporters
Special thanks to these amazing people
👏
Stargazers
👏
Forkers
More Previews
Image full screen preview
Video full screen preview
License
This project is licensed under the terms of the MIT license.
Otherwhise, if not present, false or undefined, FileItem will display the result on the InfoLayer.
5 Oct 10, 2022
214 Dec 22, 2022
83.7k Jan 3, 2023
593 Dec 27, 2022
9 Dec 14, 2022
83 Dec 25, 2022
4 May 20, 2022
2 Feb 22, 2022
1.3k Jan 3, 2023
399 Dec 21, 2022
132 Sep 16, 2022
3.4k Jan 4, 2023
2 Jan 6, 2022
2 Jun 20, 2022
16.6k Dec 27, 2022
3 Feb 9, 2022
1.4k Dec 30, 2022
1.4k Dec 24, 2022
8.7k Dec 29, 2022