simple-resource-preloader

Load any resources with JS with triggering events and callbacks

Usage no npm install needed!

<script type="module">
  import simpleResourcePreloader from 'https://cdn.skypack.dev/simple-resource-preloader';
</script>

README

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.

  1. Installation
  2. Basic Usage
  3. Options
  4. Events
  5. Methods and Properties
  6. Without bundler usage
  7. ES5 Usage
  8. 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 .

import SRPreloader from 'simple-resources-preloader';

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 = new SRPreloader({
    files: ['./video/intro.mp4', './video/background.mp4']
});

to execute preloader you need to run .preload() method

preloader.preload();

You can use styleVar option value in css code

.preloader::before {
    transition: width 0.1s;
    width:var(--preloader-progress);
}

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)
  1. If type of this value is not a function this key will be ignored. 

  2. This value can be true or 'true' any other values is false. 

  3. Only first DOM Element, if no DOM elements found or value is invalid it will be ignored. 

  4. First parameter of the executed function will be the error object, parameters from this array will be added after it. 

  5. 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. 

  6. 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. 

  7. 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.addEventListener('preloadend', e => {
        console.log('total loaded =' + e.detail.loaded); 
        console.log('total fails =' + e.detail.failed); 
    });
    

    preloaderror

    Error event have event.detail.error property, which contains last Error object.

    document.addEventListener('preloaderror', e => {
        console.log(e.detail.error); 
    });
    

    preloadprogress

    Progress event contains percentage value of loaded files and current speed values

    document.addEventListener('preloadprogress', e => {
        console.log(`Loaded ${e.detail.value}%`);
        console.log(`Preload speed is ${e.detail.speed.bytesSpeed} bytes/second`);  
        console.log(`Preload speed is ${e.detail.speed.value} ${e.detail.speed.units}`);
    });
    

    Methods and Properties

    Start preloader

    preloader.preload();
    

    Triggering custom event on target with additional details

    Acceptable properties eventName type is string, details type is object

    const
        eventName = 'customEvent', 
        details = {
            number:1
        };
    preloader.triggerEvent(eventName, details); 
    

    Hiding DOM element stored in preloader.

    preloader.hidePreloader();
    

    Show DOM element stored in preloader if it was hidden with 'hidePreloader()'.

    preloader.showPreloader();
    

    Update progress elements stored in progress.

    preloader.updateProgress();
    

    Getters and setters

    Set and get options parameters.

    See options section for details.

    const defaultOptions = preloader.defaultOptions; //Get options object used by default
    
    preloader.files = ['path/to/file1.ext', 'path/to/file2.ext'];
    const filesList = preloader.files;
    
    preloader.preloader = '#preloaderSelector'; 
    const preloaderElement = preloader.preloader; //Get DOM element even if selector string stored to options  
    
    preloader.progress = '#progressSelector'; 
    const progressElement = preloader.progress; //Get DOM element even if selector string stored to options
    
    preloader.writePercentsAttr = 'attribute';
    const progressAttrTxt = preloader.writePercentsAttr; 
    
    preloader.styleVar = '--variable-name';
    const styleVar = preloader.styleVar;
    
    preloader.speedTimeout = '250';
    const speedTimeout = preloader.speedTimeout; //Get number value even if string is stored to options, if value is invalid returns default value
    
    // main callback
    preloader.cbParams = [1, 'a'];
    const cbParams = preloader.cbParams;
        
    preloader.callback = (a, b) => {
        console.log(a); //expected output – 1 
        console.log(b); //expected output – 'a'
    };
    const callback = preloader.callback; 
    
    //error callback
    preloader.ifErrorParams = [1, 'a'];
    const ifErrorParams = preloader.ifErrorParams;
        
    preloader.ifError = (error, a, b) => {
        console.log(error); //expected output – Error object
        console.log(a);     //expected output – 1 
        console.log(b);     //expected output – 'a'
    };
    const ifError = preloader.ifError; 
    
    //percents changing callback
    preloader.onProgressParams = [1, 'a'];
    const onProgressParams = preloader.onProgressParams;
        
    preloader.onProgress = (progress, a, b) => {
        console.log(progress);  //expected output – integer number from 0 to 100
        console.log(a);         //expected output – 1 
        console.log(b);         //expected output – 'a'
    };
    const onProgress = preloader.onProgress; 
    

    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.

    <script type="module" src="./js/script.js"></script>
    

    To import it you can use code like this in you script

    import SRPreloader from './lib/SimpleResourcePreloader.min.js';
    

    To init preloader you need to create new object

    const preloader = new SRPreloader({
        files: ['./video/intro.mp4', './video/background.mp4']
    });
    

    to execute preloader you need to run .preload() method

    preloader.preload();
    

    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 -->
    <script src="./js/SimpleResourcePreloader.es5.min.js"></script>
    <script src="./js/script.js"></script>
    

    To init preloader you need to create new object

    var preloader = new SimpleResourcePreloader({
        files: ['./video/intro.mp4', './video/background.mp4']
    });
    

    to execute preloader you need to run .preload() method

    preloader.preload();
    

    Go back to options section


    License

    MIT