How to use it
The quick way: one line
Add the stylesheet, and add the script with data-auto. The bar and the button are created for you.
<link rel="stylesheet" href="progress.css"> ... <script src="progress.js" data-auto></script>
Or place the parts yourself
Use this when you only want one of them, or when you want to set options.
<div class="sp-bar" data-scroll-progress></div> <button class="sp-top" data-scroll-top></button> <script src="progress.js"></script>
Show the percentage as text
You have read <span data-scroll-percent>0%</span> of this page.
Measure the article, not the whole page
Most pages have comments, related posts and a footer below the article. Point the bar at the article, and it reaches 100% where the article ends.
<div class="sp-bar" data-scroll-progress data-scroll-target="#article"></div> <article id="article"> ... </article>
All options
| Setting | What it does |
|---|---|
data-auto on the script | Creates the bar and the button automatically. |
data-scroll-progress | Makes an element a progress bar. |
data-scroll-top | Makes a button scroll back to the top. The ring and the arrow are added for you. |
data-scroll-percent | Fills an element with the progress as text, such as 42%. |
data-scroll-target="#article" | Measures this element instead of the whole page. Works on all three parts. |
data-scroll-show="400" | On the button: appear after this many pixels. The default is 300. |
class="sp-bar sp-bar--bottom" | Puts the bar at the bottom of the screen. |
class="sp-top sp-top--left" | Puts the button in the left corner. |
Change the colours
Everything is a CSS variable. The bar colour can be a plain colour or a gradient.
.sp-bar {
--sp-height: 6px;
--sp-color: #ff5c8a;
--sp-track: rgba(0, 0, 0, .08);
}
.sp-top {
--sp-size: 48px;
--sp-ring: #ff5c8a;
--sp-top-bg: #ffffff;
--sp-top-color: #111111;
}Drive your own effects
The script also puts the progress on the page as the CSS variable --sp, a number from 0 to 1. You can use it anywhere in your CSS.
/* a header shadow that grows while scrolling */
header { box-shadow: 0 6px 20px rgba(0, 0, 0, calc(var(--sp) * .3)); }
/* a picture that slowly zooms */
.hero img { transform: scale(calc(1 + var(--sp) * .15)); }Why it stays smooth
- It updates at most once per frame. Fast scrolling does not cause extra work.
- The bar moves with a transform. The browser does not have to lay out the page again.
- It notices late changes. When pictures load and the page gets longer, the progress is corrected.
Accessibility
- The bar is announced as a progress bar with a value from 0 to 100.
- The button has the label "Back to top" and a visible focus outline.
- With reduced motion switched on, the button jumps to the top instead of gliding.
Common questions
Does it work in WordPress?
Yes. Add the two files to your theme, or paste the two lines into a header and footer plugin. With data-auto it appears on every page.
My site has a sticky header. The bar hides behind it.
Raise the bar above it with .sp-bar { z-index: 100000; }, or move the bar to the bottom with sp-bar--bottom.
The button covers my chat widget.
Move it to the left with the class sp-top--left, or change bottom in your own CSS.
What is in the download
progress.jsthe script, about 3 KBprogress.cssthe bar and the button, about 2 KBindex.htmlanddemo.cssthe demo page you see aboveREADME.txtandLICENSE.txtthe short guide and the MIT licence
Licence
MIT licence. Use it in personal and commercial projects, change it as you like. A link back is welcome and not required.