A dependency-free file uploader
Recommended step for projects with integrated module bundler (e.g. Webpack) or task-runner (e.g. Gulp).
npm install huply --save
- Integrate it via the import statement
import Huply from 'huply'
- Import
[PATH_TO_NODE_MODULES]/huply/dist/style.css
to your stylesheets / workflow
-
Add
lang
- Attribute to html-Tag. Otherwise english or the defined fallback language is used as default language.<html lang="en">
-
Add input field
<input
type="file"
accept=".jpeg,.jpg,.png"
multiple
class="huply-test"
/>
- Execute init-function:
const el = document.querySelector('.huply-test');
new Huply(el).init();
Every Huply-Instance can be modified by parameters:
Parameter | Required | Type |
---|---|---|
dropzoneTheme | false | string |
maxConcurrentUploads | false | number |
maxFileSize | false | number |
uploadUrl | true | string |
deleteUrl | true | string |
headers | false | object |
withCredentials | false | boolean |
preloadedFiles | false | PreloadedFileItemInterface[] |
translations | false | object |
allowedFileTypes | false | string[] |
chunkSize | false | number |
const options = {
dropzoneTheme: 'sm',
maxConcurrentUploads: 3,
maxFileSize: 3,
uploadUrl: 'http://huply-be.loc/api/upload',
deleteUrl: 'http://huply-be.loc/api/upload/{{filename}}',
headers: {
'X-API-Key': '123456789'
},
preloadedFiles: [
{
url: 'https://cdn.pixabay.com/photo/2022/03/06/05/30/clouds-7050884_960_720.jpg',
name: 'test.jpg'
},
{
url: 'https://cdn.pixabay.com/photo/2021/12/27/14/39/tulips-6897351_960_720.jpg',
name: 'test2.jpg'
},
{
url: 'data:application/octet-stream;base64, ...',
name: 'url-as-data-url.jpg'
},
],
allowedFileTypes: ['.jpeg', '.png', '.jpg'],
chunkSize: 5
};
new Huply(el, options).init();
Values: 'sm' | 'lg'
const options = {
...
dropzoneTheme: 'sm',
...
};
new Huply(el, options).init();
Number of concurrent uploads.
const options = {
...
maxConcurrentUploads: 3,
...
};
new Huply(el, options).init();
Maximum file size in megabytes (MB)
const options = {
...
maxFileSize: 3,
...
};
new Huply(el, options).init();
Huply sends files to this url by POST-Method
const options = {
...
uploadUrl: 'https://my-backend.url/upload',
...
};
new Huply(el, options).init();
Huply sends a request to delete a temporary uploaded file. Request is sent by DELETE-Method. The placeholder {{filename}} is required and will be replaced with the filename.
const options = {
...
deleteUrl: 'https://my-backend.url/upload/{{filename}},
...
};
new Huply(el, options).init();
Add additional headers to request (e.g. CSRF-Token, API-Key).
const options = {
...
headers: {
'X-API-KEY' : '123456789'
},
...
};
new Huply(el, options).init();
Add withCredentials
to request.
const options = {
...
withCredentials : true
...
};
new Huply(el, options).init();
Sets the preloaded files (e.g. from database). Size - Value in bytes.
const options = {
...
preloadedFiles: [
{
url: 'https://cdn.pixabay.com/photo/2022/03/06/05/30/clouds-7050884_960_720.jpg',
name: 'test.jpg',
size: 20000000
},
{
url: 'https://cdn.pixabay.com/photo/2021/12/27/14/39/tulips-6897351_960_720.jpg',
name: 'test2.jpg',
size: 10000000
},
{
url: 'data:image/jpeg;base64, ...',
name: 'url-as-data-url.jpg',
size: 10000000
},
],
...
};
new Huply(el, options).init();
const options = {
...
allowedFileTypes: ['.jpg', '.jpeg', '.png'],
...
};
new Huply(el, options).init();
If you need large file size uploads, huply slices the file into chunks. Chunk size in Megabytes (MB). An additional header (Content-Range) will be sent by file upload.
const options = {
...
chunkSize: 3,
...
};
new Huply(el, options).init();
Add parameters as data-attributes:
<input
accept=".jpeg,.jpg,.png"
multiple
class="huply-test"
name="huply-test"
type="file"
data-dropzone-theme="sm"
data-max-concurrent-uploads="2"
data-max-file-size="5"
data-max-files="3"
data-upload-url="http://huply-be.loc/api/upload"
data-delete-url="http://huply-be.loc/api/upload/{{filename}}"
data-preloaded-files='base64-encoded string (Decoded: [{"url":"https://cdn.pixabay.com/photo/2022/03/06/05/30/clouds-7050884_960_720.jpg","name":"test.jpg"},{"url":"https://cdn.pixabay.com/photo/2021/12/27/14/39/tulips-6897351_960_720.jpg","name":"test2.jpg"},{"url":"https://cdn.pixabay.com/photo/2020/03/26/10/58/norway-4970080_960_720.jpg","name":"test3.jpg"}])'
data-chunk-size="3"
/>
and initialize it:
new Huply(el).init();
You can choose between english (en) and german (de) as default translations. Add a lang-attribute to HTML-Tag: <html lang="en">
.
If you need an individual translation you can use a global variable:
window.huplyTranslations {
chooseFiles: 'Choose files',
chooseFile: 'Choose file',
allowedFileTypes: 'Allowed file types: {{allowedFileTypes}}',
maxFileSize: 'Maximum file size: {{maxFileSize}} MB',
fileItemStatusWaiting: "In queue",
fileItemStatusUploading: "Uploading ...",
fileItemStatusUploaded: "Uploaded",
fileItemStatusPreloaded: "Already uploaded",
fileItemStatusError: "An error occured.",
fileItemStatusErrorFileSize: "The file size exceeds the maximum size: {{maxFileSize}} MB",
fileItemStatusErrorFileType: "The file type is not allowed. Allowed file types: {{allowedFileTypes}}",
delete: "Delete"
}
If you need additional functionality, you can subscribe to events published by huply.
A file was added.
const huply = new Huply(el).init();
huply.on('fileAdded', function(fileItem) {
});
A file was uploaded.
const huply = new Huply(el).init();
huply.on('fileUploaded', function(fileItem) {
});
All files were uploaded.
const huply = new Huply(el).init();
huply.on('filesUploaded', function() {
});
A file was deleted.
const huply = new Huply(el).init();
huply.on('fileDeleted', function(fileItem) {
});
Status of added file changed.
const huply = new Huply(el).init();
huply.on('fileDeleted', function(fileItem) {
});
Adds a file item to the preloaded file list.
const huply = new Huply(el).init();
const fileItem = {
name: 'test123.jpg',
size: 200000,
// https://test.xyz OR Data url (data:image/jpeg;base64,....) OR empty string
url: ''
}
huply.addFileItem(fileItem);
The backend needs two endpoints:
- Processing the file upload (default and chunked)
- Delete temporary uploaded files
You need to fill the uploadUrl
- Parameter.
Every new upload will be placed in a temporary upload folder, because the huply upload input is only a part of a form. After submission of the form the temporary upload folder will be processed by the backend and will be placed in a persistent storage.
If it is a chunked upload, the HTTP-Header Content-Range
will be added.
HTTP-Method: POST
HTTP-Body (JSON
):
{
file: FILE-CONTENT
}
The response includes the filename generated by the backend. It is possible that the backend renames the filename because of special characters in the filename or duplicate filenames.
The frontend needs to know this the new filename. Every successful upload returns the HTTP-Status Code 200
.
HTTP-Status Code: 200
HTTP-Body (JSON
):
{
filename: "test.jpg"
}
You need to fill the deleteUrl
- Parameter.
Uploaded files will be stored in a temporary folder. If they are deleted by the frontend, the backend needs to know it.
Every successful deletions returns the HTTP-Status Code 200
.
HTTP-Method: DELETE
HTTP-Parameter: The filename will be sent as GET
-Parameter. The {{filename}} placeholder will be replaced by huply. (e.g. https://my-url.com/upload/{{filename}})
HTTP-Status Code: 200
This project is available under the MIT license.