filebokz
v0.1.3
Published
A tiny, dependency-free, highly customizable and configurable, easy to use file input with some pretty sweet features.
Downloads
35
Maintainers
Readme
filebokz
A tiny, dependency-free, highly customizable and configurable, easy to use file input with some pretty sweet features.
Features
- Tiny (JS ~9kb + CSS ~1kb = ~10kb total minified [add an additional ~4kb if using the theme])
- Zero dependencies
- Use as little (or as much) HTML markup as you want
- Optional default CSS styling (which looks really cool)
- Drag-and-drop
- Append files to the input
- Remove individual files from the input
- Drag files out of the box to remove from the input
- Drag files between multiple
filebokz
elements - Files are all managed with the
file
input, so they are submitted with your form and AJAX isn't required (however you can definitely use it if you wish) - Preview images before they are uploaded to your server (and specify images or HTML content to display for files that aren't images)
- Specify allowed file extensions, max number of files, max individual file size, and max total file size, as well as the error messages that are displayed when those rules are broken (and specify images or HTML content to display for files that aren't images)
- Pretty much everything is configurable and flexible
Browser Support
| Edge | Firefox | Chrome | Safari | iOS Safari | Samsung | Opera | | --------- | --------- | --------- | --------- | --------- | --------- | --------- | | >=80 | >=50 | >=58 | >=11 | Yes* | Yes* | >=45
*Not really sure about which exact versions that are supported currently
Basically any browser version made after 2016 should work.
Demo
Visit https://filebokz.js.org
Installation
Manual Download
Download the latest version of filebokz and then place the following HTML in your page's head element:
<script type="text/javascript" src="dist/filebokz.min.js"></script>
<link rel="stylesheet" href="dist/filebokz.min.css" />
<!--Optional theme-->
<link rel="stylesheet" href="dist/filebokz-theme.min.css" />
CDN (Courtesy of jsDelivr)
Place the following HTML in your page's head element (check to make sure the version in the URLs are the version you want):
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/kodie/[email protected]/dist/filebokz.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/kodie/[email protected]/dist/filebokz.min.css" />
<!--Optional theme-->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/kodie/[email protected]/dist/filebokz-theme.min.css" />
NPM
npm install filebokz --save
// ES6
import filebokz from 'filebokz'
// CommonJS
const filebokz = require('filebokz')
GPM
gpm install kodie/filebokz --save
Bower
bower install kodie/filebokz --save
Usage
Basic HTML Structure
<div class="filebokz">
<input type="file" name="my-file" />
<label for="my-file">
<strong class="no-files">Choose a file</strong>
<span class="no-files is-draggable">or drag it here</span>
<span class="files"></span>
<span class="error-msg"></span>
</label>
</div>
The filebokz([elements], [applyClass])
Function
Initiates filebokz.
Parameters
- elements - The elements to target. Accepts a string to pass into
document.querySelectorAll()
, aNodeList
instance, or anHTMLElement
instance. (Defaults to.filebokz
) - applyClass - A class name to apply to all matching elements. Set to
false
to not apply any class. (Defaults tofilebokz
)
Examples
window.addEventListener('load', function () {
filebokz()
filebokz('.custom-filebokz', false)
filebokz(document.getElementById('my-filebokz'))
filebokz(document.getElementsByClassName('file-upload'))
})
Classes
Use these classes on elements inside of the filebokz
element to customize your input.
error
Elements with this class will be hidden unless the root filebokz
element has this class which is added if any errors occur.
error-msg
Elements with this class will have their contents replaced with any errors that occur.
file
If any elements have the files
class, elements are appended to them with this class for displaying file names and/or previews when files are added to the input.
file-count
Elements with this class will have their contents replaced with the number of files in the input.
files
Elements with this class will have elements appended to them with the file
class for displaying file names and/or previews when files are added to the input.
file-previews
If displaying file previews, apply this class to any elements with the files
class for fancier styling (when filebokz-theme.css
is used).
has-files
Elements with this class will be hidden unless the root filebokz
element has this class which is added if the input has files.
in-focus
Elements with this class will be hidden unless the root filebokz
element has this class which is added if the input is in focus.
is-advanced
Elements with this class will be hidden unless the root filebokz
element has this class which is added if the browser supports advanced features.
is-draggable
Elements with this class will be hidden unless the root filebokz
element has this class which is added if the browser supports drag-and-drop.
is-dragging
Elements with this class will be hidden unless the root filebokz
element has this class which is added if a file is being dragged over it.
is-removing
Elements with this class will be hidden unless the root filebokz
element has this class which is added if a file is being dragged out of the file box and being removed.
is-transferring
Elements with this class will be hidden unless the root filebokz
element has this class which is added if a file is being dragged out of the file box and being moved to another filebokz
element.
js-enabled
Elements with this class will be hidden unless the root filebokz
element has this class which is added after the JavaScript has been ran (thus meaning the browser supports JavaScript).
no-files
Elements with this class will be hidden if the root filebokz
element has the class has-files
which is added if the input has files.
no-js
Add this class to your root filebokz
element if you do not wish for the JavaScript to do anything with it (mainly used for demo purposes).
not-in-focus
Elements with this class will be hidden if the root filebokz
element has the in-focus
class which is added if the input is in focus.
not-advanced
Elements with this class will be hidden if the root filebokz
element has the is-advanced
class which is added if the browser supports advanced features.
not-draggable
Elements with this class will be hidden if the root filebokz
element has the is-draggable
class which is added if the browser supports drag-and-drop.
not-dragging
Elements with this class will be hidden if the root filebokz
element has the is-dragging
class which is added if a file is being dragged over it.
not-removing
Elements with this class will be hidden if the root filebokz
element has the is-removing
class which is added if a file is being dragged out of the file box and being removed.
not-transferring
Elements with this class will be hidden if the root filebokz
element has the is-transferring
class which is added if a file is being dragged out of the file box and being moved to another filebokz
element.
remove
Add this class to an element inside of the files
element's content
, content-before
, or content-after
data attributes so that when the element is clicked, it removes the file from the input.
size
Elements with this class will have their contents replaced with the combined file size of all files in the input.
Root Element Attributes
Apply these attributes with the data-
prefix to your filebokz
element to configure your input. (ex. data-max-file-size="5120"
)
allowed-extensions
A comma seperated (no spaces) list of allowed file extensions. Defaults to allowing any file extension. Add [none]
to this list to allow files without extensions.
allowed-extensions-error-msg
The error message that is displayed when a user tries to upload a file that isn't in the allowed-extensions
list. Any instances of {variable}
will be replaced with the list of allowed file extensions. (Defaults to Only the following file types are allowed: {variable}.
)
appendable
Set this to false
to replace the files in the input when a file is selected rather than adding it. (Defaults to true
)
auto-submit
Set this to true
to automatically submit the parent form when a file is uploaded. (Defaults to false
)
error-display-animation-duration
The number of milliseconds after the error-display-duration
before clearing out the contents of the error-msg
element after an error has occurred. (Defaults to 250
)
error-display-duration
The number of milliseconds before removing the error
class from the filebokz after an error has occurred. (Defaults to 3000
)
max-files
The maximum number of files that are allowed to be uploaded. This is only applied if the input has the multiple
attribute. (Defaults to null
[no limit])
max-files-error-msg
The error message that is displayed when a user tries to upload more files than max-files
allows. Instances of {variable}
are replaced with the value of max-files
and instances of {s}
are replaced with an "s" if that number is more than 1, otherwise it is replaced with nothing. (Defaults to A maximum of {variable} file{s} can be uploaded.
)
max-file-size
The maximum size of a single file that is allowed to be uploaded. (Defaults to null
[no limit])
max-file-size-error-msg
The error message that is displayed when a user tries to upload a file that is bigger than what max-file-size
allows. Instances of {variable}
are replaced with the value of max-file-size
. (Defaults to File size cannot exceed {variable}.
)
max-size
The maximum size of all files combined that is allowed to be uploaded. (Defaults to null
[no limit])
max-size-error-msg
The error message that is displayed when a user tries to upload files whose combined file size is bigger than what max-size
allows. (Defaults to Total combined file size cannot exceed {variable}.
)
Files Element Attributes
Apply these attributes with the data-
prefix to any element with the files
class inside of your filebokz
element to customize how each file is displayed.
These attributes (with the exception of draggable
) can have a MIME type appended to them with any +
or /
symbols swapped out for -
to customize how a specific file type is displayed (ex. content-before-image
or even more specifically: content-before-image-svg-xml
).
These attributes (with the exception of draggable
and element
) will have the following replaced with information about each file:
{name}
- The file name.{size}
- The file size (in a human readable format).{type}
- The MIME type of the file.{url}
- If the file is an image, this will be a temporary URL to the file for previewing, otherwise it will be the contents of thedata-url
attribute, and if that doesn't exist, this will be blank.
content
The content that is placed inside of the file
element. (Defaults to {name}
)
content-before
The content that is prepended to content
. (Defaults to null
[blank])
content-after
The content that is appended to content
. (Defaults to null
[blank])
draggable
Set this to false
to disable the dragging of file
elements. (Defaults to true
)
element
The type of HTML element that the file
element should be. (Defaults to span
)
url
The URL of the file preview. This is what {url}
is set to in the content
, content-before
, and content-after
attributes. (Defaults to null
[blank] unless the file is an image, in which case it is set to a temporary URL of the file for previewing.)
JavaScript
The file-added
, file-removed
, and error
events are fired to the containing filebokz element when described events happen.
Examples
var fileElement = document.querySelector('.filebokz')
fileElement.addEventListener('file-added', function (e) {
console.log('A file was added')
})
fileElement.addEventListener('file-removed', function (e) {
console.log('A file was removed')
})
fileElement.addEventListener('error', function (e) {
console.log('An error occured', e.errorType, e.errorMessage)
})
Related
colorfield - A tiny, dependency-free, color input field helper that utilizes the native color picker.
hashjump - A tiny, dependency-free JavaScript module for handling anchor links and scrolling elements into view.
kloner - A tiny, dependency-free JavaScript module for cloning/repeating elements.
minitaur - The ultimate, dependency-free, easy to use, JavaScript plugin for creating and managing modals.
vanishing-fields - A dependency-free, easy to use, JavaScript plugin for hiding and showing fields.
License
MIT. See the license file for more info.