ep | enhance your progress bars with minimal effort!

Enhance your HTML5 progress bars with minimal effort!

npm install @jh3y/ep

The progress element sometimes doesn't play nice. It never appears consistently across browsers out of the box and different browsers throw up different limitations. Because of this, the progress element is often overlooked in favor of styled div combos.

ep tackles this;

Cross browser reset and styling of HTML5 progress elements
Optional CSS helper attributes and classes
Optional JS helper for better control and interaction with progress elements. For example; to show network request status.
Plays nice in major browsers (IE10+)

Standard usage

<progress value='75'></progress><progress data-complete="true">
</progress>

Standard usage is no different to that when using the progress element as you would normally.

However, if you want to complete progress at any stage, you swap out the value attribute for a data-complete attribute.

Set progress

Value

Indeterminate

<progress></progress>

If a progress bar is indeterminate, show a standardized animation. This animation has to be applied to the progress element itself and not its pseudo elements for cross browser compatibility.

Indeterminate progress elements don't play nice in iOS Safari so use the helper class ep--indeterminate.

Positional CSS helpers

<progress class="ep--top"></progress>

ep provides some quick use CSS helpers for positioning your progress bars. For example, you may decide to have some of your progress bars fixed top as commonly seen in some web apps.

Spread CSS helper

<progress class="ep--spread" value='75'></progress><progress  class="ep--spread" data-complete="true">
</progress>

ep provides a CSS helper for changing progress bar style. Instead of from left to right and vice-versa, you can spread a progress bar out from the middle instead.

Set progress

Value

Simulate progress

<progress data-simulate="true">
</progress><progress data-complete="true">
</progress>

How about ways to simulate progress whilst background processes are taking place? We can set a simulation with a given time and animation steps. We can make it so that it never reaches 100% until we are ready. When we are ready, set the progress element to complete.

More power over this behavior can be had by using the JavaScript helpers simulate method.

Mocked progress

<progress data-mock="4">
</progress>

Maybe you'd rather just mock progress. Just set a duration(seconds) with the data-mock attribute. Using the ep JS helper, we can hook into when our mock is complete using a callback. Check the API in the docs!

Set mock speed

Value

Staggered mock progress

<progress data-staggered-mock="4">
</progress>

Add a little stagger to your mocks.

Set mock speed

Value

Timer

<progress data-timer="4">
</progress><progress data-timer="4" data-pause="true">
</progress>

Flip progress usage and use it as a timer instead. If you need to pause it any stage, use a pause attribute.

Set timer speed

Value

SASS integration

ep is written with sass using !default variables for configuration.

This allows you to import just the pieces of ep you want whilst being able to override the defaults from within your own sass code.

For example; how about overriding the color and opacity?

$ep-fg: #e74c3c;
$ep-opacity: .8;
// import with variable configuration overridden
@import '~ep/core';

JS helper

const el = document.getElementById('js-bar');
const myEp = new ep(el);

For better control over progress behavior, ep comes with a JS helper. This allows you to do various things such as hook into value changes etc.

Have a play with some of the following examples;

myEp.simulate();
const xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function() {
  if (this.readyState == 4 && this.status == 200) {
    myEp.complete();
  }
};
xhttp.open('GET', '/index.html', true);
xhttp.send();

const afterSet = (e) => {
  alert('All set!');
};
myEp.set(23, afterSet);

const onComplete = (e) => {
  alert('Completed!');
};
myEp.complete(onComplete);

myEp.setPosition(['top', 'fixed']);

myEp.simulate();

myEp.set(75);

myEp.reset();

myEp.increase();

myEp.decrease(25);

myEp.setPosition();

myEp.setSpread(true);

myEp.setSpread(false);