Simple Resources Preloader
Load any resources using vanilla JS (ES6) with triggering events and/or callbacks.
It uses ES6 class syntax, you can check browser support here.
If you need IE support you need to transpile code to ES5 with Babel or other transpiler or use converted code to ES5 version.
- Installation
- Basic Usage
- Options
- Events
- Methods and Properties
- Without bundler usage
- ES5 Usage
- License
Installation
npm install simple-resources-preloader
Basic Usage
If you are using Webpack or another bundler you can just import it. If you don't use any bundlers go to this section .
;
Then you need to create a new preloader object, only "files" is required property, but you can set it later with setter "preloader.files".
const preloader =files: './video/intro.mp4' './video/background.mp4';
to execute preloader you need to run .preload() method
preloader;
You can use styleVar option value in css code
Options
Key | Default value | Examples of other values | Type | Description |
---|---|---|---|---|
callback | hide preloader function | function(a, b){} | function\any | This function will run after preload complete without errors1 |
cbParams | [] | [1, 'any string', true] | array | Array of parameters for function stored in callback key |
debug | false | true'true' | boolean\string | You can enable additional messages in console2 |
eventEnd | 'preloadend' | 'anyString' | string | Event name that will be triggered on end of preloading |
eventError | 'preloaderror' | 'anyString' | string | Event name that will be triggered on errors |
eventProgress | 'preloadprogress' | 'anyString' | string | Event name that will be triggered on progress changes |
events | true | false'true' | boolean\string | You can disable all events triggering with the plugin2 |
eventsTarget | document | '#selector'\DOM | string\DOM object | All events will trigger on this DOM element or document3 |
files | [] | ['path\file', 'file2'] | array of stings | Files list to preload |
ifError | hide preloader function | e => console.log(e) | function\any | This function will run after preload complete with errors1 |
ifErrorParams | [] | [1, 'any string', true] | array | Array of parameters for function stored in ifError key4 |
onProgress | update percents function | e => console.log(e) | function\any | this function will be executed on every percents change1 |
onProgressParams | [] | [1, 'any string', true] | array | Array of parameters for function stored in onProgress key5 |
preloader | DOM '#preloader' | '#selector'\DOM | string\DOM object | Hide this DOM element after preload with default functions3 |
progress | NodeList '#preloader [progress]' | '.selector'\node list | string\NodeList object | This DOM elements will receive updates of progress attribute6 |
writePercentsAttr | 'txt-progress' | 'attribute-name' | 'string' | Progress elements with this attribute will get updates of text7 |
styleVar | '--preloader-progress' | '--variable-name' | 'string' | Progress elements will get update of this css variable with percentage value |
speedTimeout | 500 | '1000' | number\string | How often speed calculation must be updated (value in ms) |
-
If type of this value is not a function this key will be ignored. ↩ ↩ ↩
-
This value can be true or 'true' any other values is false. ↩ ↩
-
Only first DOM Element, if no DOM elements found or value is invalid it will be ignored. ↩ ↩
-
First parameter of the executed function will be the error object, parameters from this array will be added after it. ↩
-
First parameter of the executed function will be the loading percentage (integer number), parameters from this array will be added after it. Last parameter — speed object with value, units and bytesSpeed keys. ↩
-
All DOM Elements selected with this selector will get updates of progress attribute during loading. It's also can be outside preloader or/and event target. ↩
-
All progress DOM Elements with this attribute wil get inner text updates during loading. ↩
Events
All plugin events have event.detail.loaded and event.detail.failed properties, types is number.
preloadend
document;
preloaderror
Error event have event.detail.error property, which contains last Error object.
document;
preloadprogress
Progress event contains percentage value of loaded files and current speed values
document;
Methods and Properties
Start preloader
preloader;
Triggering custom event on target with additional details
Acceptable properties eventName type is string, details type is object
consteventName = 'customEvent'details =number:1;preloader;
Hiding DOM element stored in preloader.
preloader;
Show DOM element stored in preloader if it was hidden with 'hidePreloader()'.
preloader;
Update progress elements stored in progress.
preloader;
Getters and setters
Set and get options parameters.
See options section for details.
const defaultOptions = preloaderdefaultOptions; //Get options object used by defaultpreloaderfiles = 'path/to/file1.ext' 'path/to/file2.ext';const filesList = preloaderfiles;preloaderpreloader = '#preloaderSelector';const preloaderElement = preloaderpreloader; //Get DOM element even if selector string stored to optionspreloaderprogress = '#progressSelector';const progressElement = preloaderprogress; //Get DOM element even if selector string stored to optionspreloaderwritePercentsAttr = 'attribute';const progressAttrTxt = preloaderwritePercentsAttr;preloaderstyleVar = '--variable-name';const styleVar = preloaderstyleVar;preloaderspeedTimeout = '250';const speedTimeout = preloaderspeedTimeout; //Get number value even if string is stored to options, if value is invalid returns default value
// main callbackpreloadercbParams = 1 'a';const cbParams = preloadercbParams;preloader {console; //expected output – 1console; //expected output – 'a'};const callback = preloadercallback;
//error callbackpreloaderifErrorParams = 1 'a';const ifErrorParams = preloaderifErrorParams;preloader {console; //expected output – Error objectconsole; //expected output – 1console; //expected output – 'a'};const ifError = preloaderifError;
//percents changing callbackpreloaderonProgressParams = 1 'a';const onProgressParams = preloaderonProgressParams;preloader {console; //expected output – integer number from 0 to 100console; //expected output – 1console; //expected output – 'a'};const onProgress = preloaderonProgress;
Properties
preloader.error - Last error object
preloader.fileSizes - Array of sile sizes and loaded status
preloader.loaded - Number of successfully loaded files
preloader.noAccess - Number of loading failed files
preloader.options - Object contains current options
preloader.percents - Number from 0 to 100 loaded progress
Without bundler usage
If you want to use it as separate file without any bundler you need to copy 'SimpleResourcePreloader.js' or 'SimpleResourcePreloader.min.js' to your project folder and add type="module" attribute to your script file.
Be careful some browsers still can't import files, so you still need a bundler or transpiler to support those browsers or use ES5 version.
To import it you can use code like this in you script
;
To init preloader you need to create new object
const preloader =files: './video/intro.mp4' './video/background.mp4';
to execute preloader you need to run .preload() method
preloader;
Go back to options section
ES5 Usage
You need to connect plugin script 'SimpleResourcePreloader.es5.js' or 'SimpleResourcePreloader.es5.min.js' before your main script
<!--script src="./js/SimpleResourcePreloader.es5.js"></script--><!-- or minified version -->
To init preloader you need to create new object
var preloader =files: './video/intro.mp4' './video/background.mp4';
to execute preloader you need to run .preload() method
preloader;
Go back to options section