The comprehensive guide to use NProgress in Next.js [easy guide]

Cover Image for The comprehensive guide to use NProgress in Next.js [easy guide]
Ali Bentaleb


NProgress is a very famous library to add progress bars when navigating between pages and waiting for data to load.

That way users are convinced that something is happening.

In this tutorial, we are going to see the comprehensive guide to use this library with Next.js framework.

Add NProgress to your Next.js project

To use Nprogress in your Next.js project, we first need to Navigate to our project and:

  • Install library using npm or yarn
## npm
npm i nprogress

## yarn
yarn add nprogress
  • Then we need to copy nprogress.css_ from node_modules/nprogress/nprogress.css to styles/nprogress.css.

This will ensure that we have the necessary css file to apply to our loading screen.

Add a loading screen to your NextJS

Now let’s make our loading screen to make transition between pages, and the steps are as the follow

  • Create an app.js file inside pages folder
  • Call NProgress.start() method when route change has started‘routeChangeStart’, () => NProgress.start())
  • Call NProgress.done() to make the loading screen disappears once route change has completed‘routeChangeComplete’, () => NProgress.done())
  • Call NProgress.done() also if there is any error for terminating the loading screen‘routeChangeError’, () => NProgress.done())

Here after what app.js will look like

import '../styles/globals.css';
import '../styles/nprogress.css';

import {useRouter} from 'next/router';
import {useEffect} from 'react';

import NProgress from 'nprogress';

function MyApp({Component, pageProps}) {
	const router = useRouter();

	useEffect(() => {'routeChangeStart', () => NProgress.start());'routeChangeComplete', () => NProgress.done());'routeChangeError', () => NProgress.done());
	}, []);

	return <Component {...pageProps} />;
export default MyApp;

Now, whenever route is changed, we are able to see the blue loading bar,

and it disappears once the next page is loaded completely

nextjs project with nprogress bar in page transition

You can check my full article on how to build page transition in your Next.js project and show the loading screen on each click in the link here

Remove Spinner in NProgress

To remove Spinner in NProgress and keep only the progressive bar, set showSpinner option to false like below

import NProgress from 'nprogress';

NProgress.configure({showSpinner: false});

Change NProgress bar color

To change bar color in Next.js, open the file nprogress.css already copied in styles folder and change the class nprogress .bar to the desired one

For example turning the bar color to black

#nprogress .bar {
	background: black;

Change spinner color

Apply these changes to the spinner-icon class like the below

#nprogress .spinner-icon {
	border-top-color: black;
	border-left-color: black;

Here we apply the black color, you can choose any of your favorite colors.

Configure time loading for the bar while increasing

To configure how much time the loading bar will appear while increasing.

The speed unit unit is milliseconds.

For example to let the bar appear 5 seconds while increasing set the speed to 5000

Router.onRouteChangeComplete = () => {
	NProgress.configure({speed: 5000});


NProgress methods

NProgess let you use other advanced methods as well.

Here is the comprehensive list of methods that are for public use:


This method let you change the default value for the parameters below

The comprehensive list is as the follow

  • minimum: a minimum percentage length on which the bar will start. The default value is 0.08
  • template: is the template used to apply the bar and the spinning circle in the loading. The default value is
<div class="bar" role="bar"><div class="peg"></div></div>
<div class="spinner" role="spinner"><div class="spinner-icon"></div></div>
  • easing: it takes CSS values like ease-in-out, ease or ease-out, which is the transition attribute values.

    To learn more about the possible values, visit CSS transition in Mozilla developer. The default value is ease.

  • speed: is a number in milliseconds, and it can be increased if you wish that the bar takes more time to complete its loading. The default value is 200.

  • trickle: is a Boolean and it let you choose whether to increment the loading bar or not. The default value is true.

  • trickleSpeed: is a number in milliseconds that let you make one trickle in that frame. So if the value is set 1000, each trickle will be done after one second exactly. The default value is 800.

  • trickleRate: specifies the increase in the bar on each trickle.

    The value is then multiplied by math.random() function which return a value between 0 and 1. The default value is 0.02

  • showSpinner: is Boolean to specify whether to show the spinning circle or not. The default value is true

  • parent: is a string, and it is the html tag container of our loading screen. The default value is body

  • positionUsing: is a string containing the possible values for the CSS attribute transform. You can check possible values in CSS transform mozilla developper. The default value is ‘’

  • barSelector: is an HTML role attribute. The default value is role=“bar”

  • spinnerSelector: is an HTML role attribute. The default value is role=“spinner”

Configuring NProgress speed attribute for example would be

NProgress.configure({trickle: false});

You can do the same for the other attributes to configure them

set(value in [0,1])

Let you set a percentage of the bar.

If the value is less than the minimum the value is the minimum.

If it is more than 1, the value is 1 which the bar full length.

Otherwise the percentage set is what has been giving as an argument.

For example, if minimum: 0.08, and we do NProgress.set(0.02), the percentage set is 0.08, and if we do set(0.3), the value set is indeed 0.3.

To try it out, remove NProgress.done() in onRouteChangeComplete and you will be able to see the variations.


This method returns the NProgress status.

It checks whether the NProgress.status is of a number type, if yes it returns true, else it returns false.


Is the same as set(0.0) or more precisely NProgress.set(NProgress.settings.minimum)


Is the same as set(1.0), it accepts a boolean as a parameter. If provided and it is true, it will show the progress bar done(true)

inc (amount)

Equivalent to NProgress.set(amount+NProgress.settings.minimum). Let you increment the loading bar by an amount inc(amount), the max value that the bar could have is 0.994.


Equivalent to inc(Math.random() * Settings.trickleRate) which augments the bar on each trickleSpeed.