ldLoader

Preloading Made Easy

ldLoader is a JavaScript library that helps you control the state of your loader.

Download

ldLoader is available for downloading in its Github Repo. Or, you can get it directly with following links:

ldld.zip

You could also use ldLoader directly via CDN like jsDelivr:

Or, via npm:

npm i ldloader

Basic usage

First, include required JS and CSS files, which you can find in ldLoader's Github Repo. Then create a loader element and initialize it with ldloader constructor:

<link rel="stylesheet" type="text/css" href="ldld.css"/> <script src="ldld.js"></script>  <div id="my-loader" class="text-danger ldld bare"></div>

/* 3. create a new ldloader object with the newly added node */
var ldld = new ldloader({ root: "#my-loader" }); 
/* 4. active this loader */
ldld.on();

Result

The mechanism is simple: it provides an interface to control loaders' state by toggling CSS class 'running':

/* when on is called */
ldld.on();

/* running class will be added */
<div class="running"> ... </div>

/* when off is called */
ldld.off();

/* running class will be removed */
<div class=""> ... </div>

Built-in Loaders

ldLoader is designed to be used with custom-defined loaders or external CSS, but it's also shipped with a set of loaders.

bare
Load it

a simple spinner with a spinning double ring.

(new ldloader({root: ".ldld.bare"})).on();
<div class="ldld bare"></div>

default
Load it

the same as bare spinner, but auto centered inside a container.

(new ldloader({root: ".ldld.default"})).on();
<div class="ldld default"></div>

full
Load it

full screen spinner that occupies the whole web page.

Click Me to Dismiss

(new ldloader({root: ".ldld.full"})).on();
<div class="ldld full"></div>

Modifier
Load it

Adjust loader size with sm or em-1 classes. Applicable on default and bare loader.

Additionally, use light or dark to adjust default color. Default color is CurrentColor.

<div class="btn btn-primary">
  Loading...
  <div class="ldld bare em-1 d-inline-block dark
  ml-2 align-middle"></div>
</div>

Work with Loading Buttons

Loading Buttons is a css library for loading indicator, which provides a set of CSS that helps you design the visual appearence of loading indicator inside a HTML box element.

While Loading Buttons doesn't provide JS API, you can control Loading Buttons' state by simply using ldLoader:

var ldbtn = new ldloader({root: "#my-ldbtn"});
<div id="my-ldbtn"
class="btn btn-primary ld-ext-right"
onclick="ldbtn.toggle()">
  <span> Click Me </span>
  <div class="ld ldld bare"
       style="width:1em;height:1em">
  </div>
</div>

Click Me

Grouping

You can toggle multiple loaders with one ldLoader instance.

var ldld = new ldloader({
  root: Array.from(
    document.querySelectorAll(".my-group-1")
  )
})));

<div class="btn ld-ext-right my-group-1"> Group 1 ... </div>
<div class="btn ld-ext-right my-group-2"> Group 2 ... </div>
<div class="btn ld-ext-right my-group-1"> Group 1 ... </div>

Group 1

❤

Group 2

❤

Group 1

❤

Customization

It's quite simple to use ldLoader along with your own CSS and images. All you have to add is the "ldld" class and a ldLoader instance.

var ldld = new ldloader({root: ".ldld"});

<div class="my-btn" onclick="ldld.toggle();"> Load More </div>
<img class="ldld" src="my-awesome-loader.svg"/>

Scripting

ldLoader also provides an interface for you to script your own loader. When initializing the ldLoader instance, passing a "ctrl" object with "step" function which will be invoke repeatedly during loader is on:

var ldld = new ldloader({
  root: ".btn",
  ctrl: { step: function(t) {
    this.innerText = Math.round(t);
  }}
})));

<div class="btn btn-primary"> Click to Run </div>

Click to Run

The "t" parameter in function step is the elapsed time since the loader is on, in milliseconds, and the this object is the element in context.

Configurations

Except the configurations described above, you can also alter ldLoader's behavior by following configurations:

container: where root should be put in. default null.
- will be root.parentNode if omitted.
- will be document.body if both root and container is omitted.
root: element for your loader. default null.
- could be css selector, element, or array of css selectors/elements.
- ldLoader will create one automatically if omitted, and append it under container.
- if root is an array, ldLoader instance will work on every element in the array.
className: additional class over root. default '' and is optional.
you can also add classes directly onto the root element you provided.
activeClass: class added to root when loader is toggled on. default 'running'.
useful when working with different css libraries.
inactive-class: class added to root when loader is toggled off. default is null.
autoZ: update root's z-index automatically. default false.
baseZ: the minimal z-index of root. default 4000.
with autoZ, ldLoader keeps track of all loaders' z-index and always use larger z-index for newly toggled loaders. baseZ is then used as a base value for all auto-z loaders.
ctrl: custom animation control unit. should at least contains a member function "step(t)".
- step(t): will be invoked repeatedly by requestAnimationFrame during loading period. context (aka this) will be root.
atomic: default true. when atomic is false, you will need N ldloader.off() call to dismiss ldLoader if there was already N ldloader.on() call.

APIs

a ldLoader instance exposes following API functions:

on(delay): toggle loader on. return promise. (if delay is provided, loader will be activated after delay(ms). Promise will be resolved after activated. )
off(delay): toggle loader off. (if delay is provided, loader will be dismissed after delay(ms). Promise will be resolved after dismissed. )
toggle(state,delay): toggle loader based on state(true/false).
toggle according to current state if state is omitted. return promise ( delay works as in on / off case )

Browser Compatibility

ldLoader is compatible with all modern browsers. However, it uses two web features that will fail for IE older than version 9:

classList ( not supported by IE<=9 )
requestAnimationFrame, used by scripting feature. ( not supported by IE<=9 )

Fortunately you can easily find polyfills for both classList and requestAnimationFrame to support IE9.

License

ldLoader is released under MIT License. License file can be found under ldLoader's GitHub repository.

Comments

Any questions or suggestion? Feel free to leave comment here. :)

Load Comments