@aslamhus/fileselect v2.3.2
@aslamhus/fileselect
A library for the File API. Easily select, read, or create previews of files. FileSelect can generate previews for pdfs, audio files, video and images (including HEIC).
Github repo: https://github.com/aslamhus/fileselect
Check out some examples at https://aslamhus.github.io/fileselect/about/
Dependencies
This package depends on Alex Corvi's Heic2any and PDF.js to generate previews for Heic files and Pdfs.
Installation
npm install @aslamhus/fileselect
Installing
You can clone the repo from github:
git clone https://github.com/aslamhus/fileselect.git
or install with node
npm install @aslamhus/fileselect
Getting Started
Once you've installed or cloned the repo, simply import it:
For node users:
import { FileSelect } from '@aslamhus/fileselect';
In the browser, with no module bundler (notice the .mjs file extension)
import { FileSelect } from '../lib/FileSelect.mjs';
or add it with a script tag
<script src="../lib/FileSelect.js"></script>
Basic Usage
Note: FileSelect should only be invoked after the DOM has loaded. The basic usage allows all files types and multiple file selection. You can change these option (see Options below)
Trigger a file select window
Calling FileSelect's select
method will trigger a file select window in the browser. select
returns a promise which resolves to a FileList.
const fileSelect = new FileSelect();
fileSelect.select().then((fileList) => {
// do something with the files
});
For convenience, the returned FileList
has extra methods assigned to it: getPreviews
, getIcons
or readFiles
and toArray
.
If you want to quickly read your files you could:
const readFiles = await fileSelect.select().then((files) => files.readFiles());
Get previews of the files
Use this method to display a preview of any file object.
fileSelect.getPreview(file).then((preview) => {
// append a preview image to the document
document.body.append(preview);
});
// with the select method
const icons = await fileSelect.select().then((fileList) => fileList.getPreviews());
Read the files
To prepare to upload files, you can use the readFiles
method to read each file as a Data:URL
representing the file contents. After the files are read you can upload the file or do whatever you need to with it. The readFiles method returns an array of DataURL Objects or a single DataURL object depending on the arguments supplied. Example:
fileSelect.readFiles(myFiles).then((dataURLS) => {
// files have been read and are ready to go!
console.log(dataURLs);
});
Note: files must be instance of the File Object i.e. an object from a FileList
or a DataTransfer.
Generate a file icon of the selected file
FileSelect can create file icons for your selected files using the getIcon
method.
To dispay the file icon, simply write it to the DOM
.
FileSelect uses a set of default icons.
fileSelect.getIcon(file).then((icon) => {
// append a file icon image to the document
document.body.append(icon);
});
// with the select method
const icons = await fileSelect.select().then((fileList) => fileList.getIcons());
Remove files
Remove all files from FileSelect's file list.
fileSelect.removeFiles();
Callbacks
onFileReadComplete
Each time a file is read, onFileReadComplete
is called. You can access the file by passing your own callback into the FileSelect
constructor:
const fileSelect = new FileSelect('*', {
onFileReadComplete: function (file) {
console.log(file);
},
});
alternatively
const fileSelect = new FileSelect();
fileSelect.onFileReadComplete = (file) => {
console.log(file);
};
Error handling
The easiest way to handle errors is to add a catch block to FileSelect's methods.
const fs = new FileSelect();
fs.select()
.then((files) => {
// do something with your files
})
.catch((error) => {
// handle an invalid type error
// handle a fileSizeLimitExceeded error
});
onInvalidType
error
By default if an unallowed file type is selected, FileSelect will throw an error. You can can add your own handler by passing a function to the options object in the constructor
.
const fs = new FileSelect('*', {
onInvalidType = (err) => {
console.error('invalid type, ' + err.message);
}
});
onFileSizeLimitExceeded
error
By default if the file size limit is exceeded, FileSelect will throw an error. You can can add your own handler by passing a function to the options object in the constructor
.
const fs = new FileSelect('*', {
onFileSizeLimitExceeded = (err, fileSize, fileSizeLimit) => {
console.error('Filesize limit exceeded, ' + err.message);
}
});
Options
Allowed file types
You can specify which file types FileSelect
will accept by passing a string or array of strings as the first argument of the constructor
:
// allow jpegs and pdfs
const allowedTypes = ['image/jpeg', 'application/pdf'];
const fs = new FileSelect(allowedTypes);
// allow all images
const fs = new FileSelect('image/*');
Examples
Value | Types allowed |
---|---|
* | all files types |
image/* | all images |
video/* | all videos |
'image/png', 'video/mp4' | pngs and mp4s |
Allow multiple file selection
By default FileSelect allows multiple files to be selected. You can set this to false to restrict file select to one file only.
new FileSelect('*', { multiple: false });
Set file size limit
To set the file size limit in bytes, add this option to the constructor, or use the setFileSizeLimit
method.
const fileSelect = new FileSelect('*', { fileSize: 1024 });
fileSelect.setFileSizeLimit(2048);
File Input Element
FileSelect automatically appends a (hidden) file input element <input type='file'>
to the document's <body>
tag. The input element is required to trigger the file select. If there is already a file input element in the DOM, FileSelect will use the first one it finds. But you can tell FileSelect to use a specific FileInput
instead.
const myInput = document.querySelector('#myInput')
const fileSelect = new FileSelect("*", { fileInput : myInput}
You can also prevent FileSelect from adding a file input element to the DOM altogether. This can be useful when you are receiving a filelist or fileobject from a datatransfer
const fileSelect = new FileSelect('*', { fileInput: false });
Change color theme for the file icon previews
Use a preformatted theme:
const fileSelect = new FileSelect('*', { theme: 'red' });
For a list of supported themes see @aslamhus/fileicon documentation
or use your own colors.
const fileSelect = new FileSelect('*', {
colors: {
bg: 'transparent',
iconBg: 'coral',
textBg: 'rgba(250,250,250,0.2)',
text: '#FFF',
outline: 'white',
},
});
Use DIV
element with background-image instead of an IMG
Returns PDF and Image previews as divs instead of an img element. The element stores the mimetype and blob url in its dataset:
const fs = new FileSelect('*', { preview: { backgroundImage: true } });
Note: If you use this option, please be sure to use URL.revokeObjectURL after you have loaded the image, since an onload event cannot be attached to a background image.
Tests
Note: To run the test command, make sure you install all dependencies by running npm install
in the FileSelect directory.
`npm run test`
Examples
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago