Guide · Open source
How to use NProgress: add a slim loading bar to your app
Updated · written with AI from the project's own documentation and checked against our catalogue data
NProgress is an open-source JavaScript library that shows a thin loading bar, similar to the ones on YouTube or Medium, to signal that something is loading. This guide explains what it is, how to get the code, how developers typically use its start and done functions, and when a different tool may suit you better. The README in the source material is empty, so the details here are limited to what the repository description and our analysis state.
NProgressrstacruz/nprogress · ★ 26.3k · MIT Install options & downloads Quick start
- 1Get the code. Install NProgress with your project's package manager, or clone the repository from GitHub if you want the source files.
- 2Add the library to your page. Include NProgress in the JavaScript your project loads so its functions are available to your code.
- 3Call start when loading begins. Trigger NProgress's start function when a page change or request starts so the loading bar appears.
- 4Call done when loading ends. Trigger NProgress's done function when the content has loaded so the bar completes and disappears.
What NProgress does
NProgress displays a slim progress bar at the top of the page. Its purpose is to tell a user that something is loading, such as a page or a request.
It is a code library, not a standalone program. You add it to a web project and call it from your own code.
- Shows a thin loading bar
- Signals that content is loading
- Intended as a simple, drop-in visual cue
Install NProgress with a package manager or from the repository
The project's install method is listed as a package manager, and no prerequisites are listed. Use the package manager your project already uses to add the library.
The source also gives a command to clone the repository directly from GitHub. Cloning gives you the source files if you want to read or copy them.
git clone https://github.com/rstacruz/nprogress.gitShow and hide the bar with start and done
Developers typically call NProgress's start and done functions around page or request loading. Call start when loading begins so the bar appears, and call done when loading finishes so the bar completes and goes away.
The source material does not document other functions or settings, so check the project's homepage for further detail before relying on anything else.
- Call start when a page or request begins loading
- Call done when it finishes
- Use it in single-page apps or around slow requests
Decide whether NProgress fits your project
NProgress suits web developers who want a simple, drop-in progress bar without a large UI framework. It is a good match for JavaScript projects that want a lightweight cue for slow requests.
It is not a fit if you need a detailed progress meter with exact percentages, since the description covers only a slim bar. The last push shown is June 2022, so if you need ongoing maintenance guarantees, weigh that before adopting it.
- Good fit: single-page apps and lightweight loading cues
- Poor fit: exact percentage progress meters
- Poor fit: non-developers wanting an end-user app
Consider alternatives to NProgress
The source lists Turbolinks, Pace.js and topbar as comparable projects. The source does not compare them with NProgress on features, performance or size, so review each one's documentation against your needs.
- Turbolinks
- Pace.js
- topbar
What people use it for
- Showing a loading bar during page changes in a single-page app
- Signalling slow API or data requests to users with a thin top bar
- Adding a lightweight visual cue to a JavaScript project without a large UI framework
Frequently asked questions
Is NProgress free to use?
NProgress is released under the MIT licence, as stated in the source. Check the licence file in the repository for the full terms before using it in your project.
What are the requirements for NProgress?
The source lists no prerequisites. It is a JavaScript library, so it is intended for projects that already use JavaScript.
How do I install NProgress?
The listed install method is a package manager, and the source also gives a git clone command for the repository. The source does not provide a specific package manager command, so follow the project's homepage for exact steps.
What are the alternatives to NProgress?
The source lists Turbolinks, Pace.js and topbar as comparable projects. Each one has different scope, so compare them against what your project needs.
Does NProgress show exact percentages?
No. The source describes NProgress as a slim progress bar, not a detailed meter showing exact percentages. If you need precise progress, look for a different tool.
Is NProgress still maintained?
The last push shown is June 2022. Check the repository's activity and issues before relying on it for long-term maintenance.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
NProgress is a good choice for web developers who want a simple, drop-in loading bar for single-page apps or slow requests and who are comfortable with a small, code-only library. Pick something else if you need exact progress percentages, a full UI framework, or confident long-term maintenance, since the last push shown is June 2022.
Install options & downloads