# NProgress — Slim Progress Bar for Ajax and Page Loads

> A nanoscopic progress bar library that provides YouTube-style slim loading indicators for Ajax requests and page transitions, with zero dependencies and a minimal API.

## Install

Save in your project root:

# NProgress — Slim Progress Bar for Ajax and Page Loads

## Quick Use
```bash
npm install nprogress
```
```js
import NProgress from 'nprogress';
import 'nprogress/nprogress.css';
NProgress.start();
// ... async work ...
NProgress.done();
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-722d5eef
Author: AI Open Source