An automatic web progress bar. Inspired by pace.
If you're using a framework like React, that comes with a build system.
Run this command in your terminal:
npm i paweThen, add this in your layout (e.g. layout.tsx, +layout.svelte, etc.)
import 'pawe';If you want to use
pawedirectly in the browser.
Include this in the <head> of your HTML:
<script
type="module"
src="https://cdn.jsdelivr.net/npm/pawe"
></script>This is the default mode. This means pawe will automatically start monitoring the page load progress & expose the values as HTML attributes & CSS custom properties.
A basic progress bar.
<style>
/* 1. using CSS custom properties for values */
#progress {
/* progress bar */
width: var(--pawe-bar-percent, 0%);
background: hsl(0 0% 0%);
position: fixed;
height: 2px;
top: 0;
left: 0;
transition:
width 1s ease-out,
opacity 1s;
/* progress text (i.e. '100%') */
&::after {
content: var(--pawe-bar-percent-string) '%';
}
}
/* 2. using HTML attributes for state changes */
:root[data-pawe='idle'] #progress {
opacity: 0;
}
</style>
<div id="progress"></div>Here are all the exposed values in HTML/CSS that you can use:
| Attribute | Element | Type | Description |
|---|---|---|---|
data-pawe |
:root (<html>) |
idle | loading |
The current state of pawe. |
| Property | Range | Description |
|---|---|---|
--pawe-bar |
0 to 1 |
The augmented progress of the page load that approximates the loading in between down time of collected data points. Users generally prefer this as it provides feedback even if their connections are spotty, causing data to come down in bursts. |
--pawe-bar-percent |
0% to 100% |
'', in percent. |
--pawe-bar-percent-int |
0 to 100 |
'', floored, without unit. |
--pawe-bar-percent-string |
'0' to '100' |
'', in string type, for use with the content property. |
--pawe-progress |
0 to 1 |
The objective progress of the page load solely based on the collected data points. |
--pawe-progress-percent |
0% to 100% |
'', in percent. |
--pawe-progress-percent-int |
0 to 100 |
'', floored, without unit. |
--pawe-progress-percent-string |
'0' to '100' |
'', in string type, for use with the content property. |
You can also use the JavaScript API to get the progress values programmatically.
For the full list of available exports, see the index.ts file.
Better docs are coming soon™!
import { bar } from 'pawe';
const unsubscribe = bar.subscribe(($bar) => {
// this is equivalent to `--pawe-bar`
console.log(`bar: ${$bar}`);
});You can also use pawe in manual mode by importing from pawe/api. This means you are in charge of starting the monitoring & scaffolding any other load signals you want to track.
// note the different import!
// * `pawe` - automatic mode
// monitoring is started automatically
// * `pawe/api` - manual mode
// only the api is exposed & no side effects are ran
import { monitorDOM, createLoad, progress } from 'pawe/api';
// log the progress values as we add loads
const unsubscribe = progress.subscribe(($progress) => {
console.log(`progress: ${$progress}`);
});
// add monitoring of the DOM (skipping the rest)
monitorDOM();
// add your own load signal to the calculated progress
const load = createLoad();
console.log('starting load...');
console.log('loaded: 0%');
// simulate loading
load.set(0.5);
console.log('loaded: 50%');
// mark as finished after 1 second
setTimeout(() => {
load.finish();
// or
// `load.set(1)`
}, 1000);
// the load acts as a promise that will resolve when it hits `1`
await load;
console.log('loaded: 100%');// note the different import!
// * `pawe` - automatic mode
// monitoring is started automatically
// * `pawe/api` - manual mode
// only the api is exposed & no side effects are ran
import { createPool, createLoad, createProgress, createBar } from 'pawe/api';
// where all the loads are stored
const pool = createPool();
// create a load signal
const load = createLoad(pool);
// ^^^^
// note that `pool` is passed as the first argument!
// this is so that the load signal is added to our pool
// instead of the global one
// create a progress signal
const progress = createProgress(pool);
// create a progress bar (for UI)
const bar = createBar(progress);
// use the progress values
const unsubscribeProgress = progress.subscribe(($progress) => {
console.log(`progress: ${$progress}`);
});
const unsubscribeBar = bar.subscribe(($bar) => {
console.log(`bar: ${$bar}`);
});If you want to bypass AJAX requests from being tracked by pawe, you can pass in the non-standard pawe property. It will be removed from the final config/instance before being sent.
const resp = await fetch('https://example.com', {
pawe: 'bypass', // add this to bypass tracking
});const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://example.com');
xhr.pawe = 'bypass'; // add this to bypass tracking
xhr.send();Include the following in your tsconfig.json to get type hints for the above mentioned pawe property.
{
"compilerOptions": {
"types": ["pawe/client"]
}
}DOM- Track load events from DOM elements that are statically & dynamically added to the pagedocument.readyStateuntilcomplete<img>load (both eager & lazy)<video>load (when it starts loading until it's ready to play)<audio>load (when it starts loading until it's ready to play)<iframe>load<object>load<embed>load
fetch- Track data stream fromfetchrequestsXMLHttpRequest- Trackprogressevents fromXMLHttpRequests
MIT