bar-of-progress

It is a small, easy-to-use, and dependency-free loading bar component.

Features

  1. No Dependency: It is not tied to any specific framework.

  2. Small Size: Less than 500 bytes when compressed with Brotli (less than 600 bytes when compressed with gzip).

  3. Easy to Use: It can be used with just a few lines of code. It also supports TypeScript.


Installation

The command npm i @badrap/bar-of-progress is used with Node.js package manager npm to install a package called "@badrap/bar-of-progress". This package provides a lightweight, easy-to-use progress bar component that has no dependencies on any specific framework. After installation, you can use the progress bar with just a few lines of code. TypeScript is also supported.

Cautions

No specific cautions are mentioned regarding the usage of the "@badrap/bar-of-progress" package. However, there are some general cautions to consider when using Node.js packages in general:

  • Name
    Compatibility
    Type
    Cautions
    Description

    You should check if the "@badrap/bar-of-progress" package is compatible with the version of Node.js you are currently using.

  • Name
    Dependency management
    Type
    Cautions
    Description

    Once this package is installed, it will be automatically added to the package.json file. This file is used to manage dependencies in the project and ensure that the required version of the package is always installed.

  • Name
    Security
    Type
    Cautions
    Description

    When installing npm packages, it is important to always verify that they are provided by a trusted source. Packages from unknown sources can pose security risks to your code.

  • Name
    Maintenance
    Type
    Cautions
    Description

    You should keep the package up to date and be prepared for compatibility issues that may arise during version updates.

Installation

npm i @badrap/bar-of-progress

Usage

Import the package and create an instance of the progress bar.

  • Name
    Call the .start() method.
    Type
    Usage
    Description

    Call the .start() method to display the progress bar and start the animation.

  • Name
    Call the .finish() method.
    Type
    Usage
    Description

    Call the .finish() method to end the progress bar animation.

Cautions

  • Name
    Quick task
    Type
    Cautions
    Description

    When .start() is called, the progress bar is not immediately visible. Instead, there is a delay of 80 milliseconds to avoid showing the progress bar for tasks that complete very quickly. You can modify this (and other) behavior by referring to customization options.

  • Name
    Reusability
    Type
    Cautions
    Description

    When using a progress bar instance, the animation starts from the beginning with each page transition.

Usage

import ProgressBar from "@badrap/bar-of-progress";

const progress = new ProgressBar();

.start()

progress.start();

.finish()

  setTimeout(() => {
    progress.finish();
  }, 1000);

Customization

The shape and behavior of the progress bar can be (slightly) customized through constructor parameters. Here are the options and their default values.

Description

  • Name
    size
    Type
    Description
    Description
    • The size (thickness) of the progress bar.

    • Numeric values are converted to pixels (px).

  • Name
    color
    Type
    Description
    Description
    • The color of the progress bar.

    • It can also be used for the glow effect around the bar.

  • Name
    class
    Type
    Description
    Description
    • The class name used for the progress bar element.
  • Name
    delay
    Type
    Description
    Description
    • The number of milliseconds to wait before the progress bar animation starts after calling .start().

Customization

const progress = new ProgressBar({

  // The size (height) of the progress bar.
  // Numeric values get converted to px.
  size: 2,

  // Color of the progress bar.
  // Also used for the glow around the bar.
  color: "#29e",

  // Class name used for the progress bar element.
  className: "bar-of-progress",

  // How many milliseconds to wait before the progress bar
  // animation starts after calling .start().
  delay: 80,
});

Example

This is a method of showing the progress bar animation during page transitions using the routing events in Next.js. The Router.events used here represents the events provided by the Router object in Next.js.

Additional Explanation

  • Name
    routeChangeStart
    Type
    Example
    Description

    This is the event that occurs when a route change is about to start. When this event occurs, progress.start() is called to start the progress bar animation.

  • Name
    routeChangeComplete
    Type
    Example
    Description

    This is the event that occurs when a route change is completed. When this event occurs, progress.finish() is called to end the progress bar animation.

  • Name
    routeChangeError
    Type
    Example
    Description

    This is the event that occurs when an error happens during a route change. When this event occurs, progress.finish() is called to end the progress bar animation.


The useEffect is a React Hook that runs the code inside it when the component is mounted (or when router.events changes). In this code, handlers are registered for each of the events mentioned earlier.

Additionally, useEffect returns a clean-up function. This function is called when the component is unmounted or before the next useEffect is executed. This code prevents memory leaks.

_app.js

Router.events.on('routeChangeStart', onRouteChange)

Router.events.on('hashChangeStart', onRouteChange)

const progress = new ProgressBar({
size: 4,
color: '#F7AB0A',
className: 'z-50',
delay: 100,
})

Router.events.on('routeChangeStart', () => progress.start())
Router.events.on('routeChangeComplete', () => progress.finish())
Router.events.on('routeChangeError', () => progress.finish())

useEffect(() => {
const handleRouteChangeStart = () => {
  progress.start()
}

const handleRouteChangeComplete = () => {
  progress.finish()
}

const handleRouteChangeError = () => {
  progress.finish()
}

router.events.on('routeChangeStart', handleRouteChangeStart)
router.events.on('routeChangeComplete', handleRouteChangeComplete)
router.events.on('routeChangeError', handleRouteChangeError)

return () => {
  router.events.off('routeChangeStart', handleRouteChangeStart)
  router.events.off('routeChangeComplete', handleRouteChangeComplete)
  router.events.off('routeChangeError', handleRouteChangeError)
}

}, [router.events])