NProgress — Slim Progress Bar for Ajax and Page Loads

Introduction

NProgress is a lightweight JavaScript library that renders a slim, YouTube-inspired progress bar at the top of the page. It is commonly used to indicate loading state during Ajax requests or route transitions in single-page applications.

What NProgress Does

• Displays a thin animated progress bar at the top of the viewport during async operations
• Provides trickle animation that slowly increments the bar to simulate progress when actual progress is unknown
• Exposes a minimal API with start(), done(), set(), and inc() methods
• Works with any framework or vanilla JavaScript without dependencies
• Includes a small spinner indicator that can optionally appear alongside the bar

Architecture Overview

NProgress manipulates a single DOM element that it creates and appends to the document body. The bar position is tracked as a number between 0 and 1. When trickle mode is active, a timer increments the value by random small amounts to give the appearance of progress. CSS transitions handle the animation, keeping the JavaScript footprint minimal at around 2 KB minified and gzipped.

Self-Hosting & Configuration

• Install via npm or include the script and CSS from a CDN
• Import both the JS module and the CSS file (or copy the styles into your own stylesheet)
• Configure minimum (starting percentage), trickleSpeed (ms between increments), and easing/speed for the CSS transition
• Disable the spinner with NProgress.configure({ showSpinner: false })
• Attach to your HTTP client (Axios interceptors, fetch wrapper) to auto-start and auto-stop on requests

Key Features

• Zero dependencies and under 2 KB gzipped for minimal impact on bundle size
• Drop-in integration with Axios, jQuery Ajax, or any promise-based HTTP client
• Trickle mode simulates progress realistically when actual completion percentage is unknown
• Fully customizable via CSS variables for color, height, and z-index
• Framework-agnostic with community wrappers for React, Vue, Next.js, and Nuxt

Comparison with Similar Tools

• pace.js — automatically monitors Ajax, document readiness, and event loops; NProgress is manually triggered, giving developers more control
• topbar — similar slim progress bar with a slightly different API; NProgress has wider adoption and more framework integrations
• Loading Bar (Vue/React) — framework-specific loading bar components that couple to router events; NProgress works anywhere
• Native browser loading indicator — browsers show a tab spinner but offer no customization; NProgress provides branded, styled feedback

FAQ

Q: How do I use NProgress with Next.js route changes? A: Listen to Next.js Router events: call NProgress.start() on routeChangeStart and NProgress.done() on routeChangeComplete and routeChangeError.

Q: Can I change the color of the progress bar? A: Yes. Override the #nprogress .bar CSS rule with your preferred background color, or adjust the CSS custom properties if using a wrapper.

Q: Does NProgress track real upload or download progress? A: No. It simulates progress with trickle mode. For real progress tracking, call NProgress.set(value) manually from an XMLHttpRequest progress event or fetch stream.

Q: Is NProgress still maintained? A: The library is stable and feature-complete. It receives occasional maintenance updates. Its small scope means there is little that needs changing.

Sources

• https://github.com/rstacruz/nprogress
• https://ricostacruz.com/nprogress/