Scroll Progress - Quick Start Guide

1-Minute Setup

Get started with scroll progress indicators in three simple steps:

That's it! You now have a working scroll progress indicator at the top of your page.

Quick Reference

Position Options

Position	CSS Override	Description
Top (default)	`top: 0; left: 0;`	Horizontal bar at top of viewport
Bottom	`bottom: 0; top: auto;`	Horizontal bar at bottom of viewport
Left	`left: 0; width: 4px; height: 0;`	Vertical bar on left edge
Right	`right: 0; left: auto; width: 4px; height: 0;`	Vertical bar on right edge

Thickness Options

Size	Height (Horizontal)	Width (Vertical)
Thin	`2px`	`2px`
Default	`4px`	`4px`
Thick	`8px`	`8px`

Color Options

Style	CSS
Default Green	`background-color: #4caf50;`
Blue	`background-color: #2196f3;`
Gradient	`background: linear-gradient(90deg, #667eea 0%, #764ba2 100%);`
Dark	`background-color: #333;`

HTML Structure

Basic Top Bar (Default)

Bottom Position


.scroll-progress {
    position: fixed;
    bottom: 0;      /* Change from top to bottom */
    top: auto;
    left: 0;
    height: 4px;
    background-color: #4caf50;
    z-index: 1000;
    width: 0;
}

Vertical Bar (Left Side)


.scroll-progress {
    position: fixed;
    top: 0;
    left: 0;
    width: 4px;      /* Width instead of height */
    height: 0;       /* Will be updated by JavaScript */
    background-color: #4caf50;
    z-index: 1000;
}


// Update height instead of width for vertical bars
window.addEventListener('scroll', function() {
    var scrollTop = document.documentElement.scrollTop || document.body.scrollTop;
    var scrollHeight = (document.documentElement.scrollHeight || document.body.scrollHeight) - document.documentElement.clientHeight;
    var scrollPercent = scrollTop / scrollHeight * 100;
    document.querySelector('.scroll-progress').style.height = scrollPercent + '%';
});

Custom Colors


/* Blue theme */
.scroll-progress {
    background-color: #2196f3;
}

/* Gradient */
.scroll-progress {
    background: linear-gradient(90deg, #667eea 0%, #764ba2 100%);
}

/* Dark theme */
.scroll-progress {
    background-color: #333;
}

/* Custom brand color */
.scroll-progress {
    background-color: var(--brand-primary);
}

Custom Thickness


/* Thin bar (2px) */
.scroll-progress {
    height: 2px;  /* For horizontal bars */
}

/* Thick bar (8px) */
.scroll-progress {
    height: 8px;  /* For horizontal bars */
}

/* Very prominent (12px) */
.scroll-progress {
    height: 12px;
}

How It Works

The scroll progress indicator calculates the scroll percentage and updates the bar width (or height for vertical bars) accordingly.

Scroll Calculation Formula


window.addEventListener('scroll', function() {
    // Get current scroll position
    var scrollTop = document.documentElement.scrollTop || document.body.scrollTop;

    // Calculate total scrollable height
    var scrollHeight = (document.documentElement.scrollHeight || document.body.scrollHeight) - document.documentElement.clientHeight;

    // Calculate percentage
    var scrollPercent = scrollTop / scrollHeight * 100;

    // Update progress bar width
    document.querySelector('.scroll-progress').style.width = scrollPercent + '%';
});

Formula Breakdown:

scrollTop = Current vertical scroll position in pixels
scrollHeight = Total scrollable height (document height - viewport height)
scrollPercent = (scrollTop / scrollHeight) × 100
Result is applied to width property (or height for vertical bars)

Common Patterns

Blog Article Progress

Subtle top bar showing reading progress through long-form content:


.scroll-progress {
    height: 3px;
    background-color: #2196f3;
    opacity: 0.8;
}

Documentation Navigation

Vertical bar on left side for technical documentation:


.scroll-progress {
    position: fixed;
    top: 0;
    left: 0;
    width: 5px;
    height: 0;
    background: linear-gradient(180deg, #667eea 0%, #764ba2 100%);
}

Landing Page

Prominent gradient bar for single-page marketing sites:


.scroll-progress {
    height: 6px;
    background: linear-gradient(90deg, #f093fb 0%, #f5576c 100%);
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

Dark Theme

Subtle light bar for dark-themed websites:


.scroll-progress {
    height: 2px;
    background-color: rgba(255, 255, 255, 0.7);
}

Accessibility

Reduced Motion Support

Respect user preferences for reduced motion:


/* Hide for users who prefer reduced motion */
@media (prefers-reduced-motion: reduce) {
    .scroll-progress {
        display: none;
    }
}

Best Practices

Non-intrusive: The progress bar is purely visual and doesn't interfere with content or navigation
Color contrast: Ensure sufficient contrast between the progress bar and background
Performance: The scroll listener is lightweight and uses efficient DOM queries
No ARIA needed: Progress bars are decorative and don't require ARIA labels
Smooth updates: Width/height updates are smooth due to the percentage calculation

Accessibility Note: Scroll progress indicators are considered decorative elements and don't need ARIA attributes. They provide visual feedback but shouldn't be the only way users understand content length.

Integration with RSL

Works With All Layouts

Scroll progress works seamlessly with RSL's grid system and other components:





        


    
    

    
    
        
            Content here...
            More content...

Z-Index Stacking

The progress bar has z-index: 1000 to ensure it appears above most content. Adjust if needed:


/* Increase if you have modals or other high z-index elements */
.scroll-progress {
    z-index: 9999;
}

Pro Tips

Smooth Transitions

Add a transition for smoother visual updates (optional):


.scroll-progress {
    transition: width 0.1s ease-out;
}

Multiple Bars

You can have both horizontal and vertical bars simultaneously:

Performance

The scroll listener is already optimized, but for very long pages you can add throttling:


let ticking = false;
window.addEventListener('scroll', function() {
    if (!ticking) {
        window.requestAnimationFrame(function() {
            var scrollTop = document.documentElement.scrollTop || document.body.scrollTop;
            var scrollHeight = (document.documentElement.scrollHeight || document.body.scrollHeight) - document.documentElement.clientHeight;
            var scrollPercent = scrollTop / scrollHeight * 100;
            document.querySelector('.scroll-progress').style.width = scrollPercent + '%';
            ticking = false;
        });
        ticking = true;
    }
});

Troubleshooting

Bar Not Showing

Issue: Progress bar is not visible

Verify CSS file is loaded:
Check that HTML element exists:
Ensure JavaScript is loaded:
Check z-index conflicts with other fixed elements
Verify page has enough content to scroll

Bar Not Updating

Issue: Progress bar doesn't update on scroll

Check browser console for JavaScript errors
Verify scroll-progress.js is loaded after the DOM
Ensure the selector .scroll-progress matches your HTML
Test with vertical bar if using modified JavaScript

Bar Shows at 100% Immediately

Issue: Progress bar is fully filled without scrolling

Page might not have scrollable content (height too short)
Check CSS is setting width: 0 initially (not 100%)
Verify no conflicting CSS rules setting width to 100%

Performance Issues

Issue: Page scrolling feels sluggish

Use the throttled version with requestAnimationFrame shown in Pro Tips
Avoid adding CSS transitions longer than 0.1s
Check for other scroll listeners that might conflict

Next Steps

See Examples

View scroll-progress.html for realistic use cases

Copy Templates

Use playground.html as a starting point

Explore More

Browse all RSL Components and examples

Back to Examples