React TopLoader 🏋🏼‍♂️

Displays a top loader progress while navigating on a different page

Table of Contents

• Getting started
• API Reference
  • React Components
    • TopLoader
    • TopLoaderProgressBar
  • React Hooks
    • useTopLoaderApi
    • useTopLoader
  • React Context API
    • TopLoaderContext
    • TopLoaderProvider
  • Next.js Integration
    • useRouter
  • Usage examples
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using react-top-loader in your projects:

npm i @alessiofrittoli/react-top-loader

or using pnpm

pnpm i @alessiofrittoli/react-top-loader

Overview

Progress updates aren't managed via React state updates but they're based on simple CSS modifications.

This library listen for link clicks, history push and replace states and checks effective navigation in order to start updating navigation progresses.

To avoid negatively impacting your application INP value we use the useDeferCallback exported by @alessiofrittoli/react-hooks library which defers tasks attached to user interactions.

API Reference

React Components

TopLoader

Displays a top loader progress while navigating on a different page.

⚠️ This Component should be mounted once, preferably in the root layout of your application and shouldn't be unmounted when navigating on a different page.

This Component internally use the TopLoaderProvider Component in order to expose the useTopLoaderApi widely in your app.

| Property | Type | Description | | ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Component | React.FC<TopLoaderProgressBarProps> | A React Component which renders a custom progress bar. It must accepts TopLoaderProgressBarProps as props. |

Other properties are inherited by the TopLoaderProviderProps and TopLoaderProgressBarProps.

TopLoaderProgressBar

Simple TopLoader progress bar.

It requires a React.RefObject through the progressBarRef property which will be used to update the progress bar styles based on the current progress value.

This Component is internally used by the TopLoader Component but it is exported for custom implementations.

TopLoaderProgressBarProps

| Property | Type | Description | | ---------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | progressBarRef | React.RefObject<HTMLDivElement\|null> | The React.RefObject attached to the HTMLDivElement which is then used to update styles based on the current progress value. |

Other properties are inherited by the React.ComponentProps<'div'> type and not documented here.

React Hooks

useTopLoaderApi

TopLoader base API React hook.

It provides status and methods needed to easly handle continuous progress update.

This hook is internally used by TopLoaderProvider Component but it is exported for custom implementations.

Types

UseTopLoaderApiOptions

Defines accepted properties in useTopLoaderApi options.

• onStart?: OnStartHandler - A custom callback executed when the start method is called.
• onTick?: OnTickHandler - A custom callback executed when the progress value is updated.
• onStop?: OnStopHandler - A custom callback executed when the stop method is called.

OnStartHandler

A custom callback executed when the start method is called.

() => void

OnTickHandler

A custom callback executed when the progress value is updated.

( progress: number ) => void

| Parameter | Type | Description | | ---------- | -------- | -------------------------------------------- | | progress | number | The progress value number from 0 to 100. |

OnStopHandler

A custom callback executed when the stop method is called.

() => void

| Parameter | Type | Default | Description | | ----------------- | ------------------------ | ------- | -------------------------------------------------------------- | | options | UseTopLoaderApiOptions | {} | An object defining custom options. | | options.onStart | OnStartHandler | - | A custom callback executed when the start method is called. | | options.onTick | OnTickHandler | - | A custom callback executed when the progress value is updated. | | options.onStop | OnStopHandler | - | A custom callback executed when the stop method is called. |

Type: UseTopLoaderApi

An object defining progress status and methods.

• playing: React.RefObject<boolean> - A React.RefObject indicating whether the work is currently playing or not.
• progress: React.RefObject<number> - A React.RefObject indicating the current progress value.
• start: () => void - Start the TopLoader work.
• tick: ( amount?: number ) => boolean - Tick TopLoader progress.
• stop: () => void - Set progress to 100 and stop the TopLoader work.

useTopLoader

Access to the TopLoader React Context API.

Type: UseTopLoaderApi

This hooks returns the useTopLoaderApi result exposed through the TopLoaderContext.

React Context API

TopLoaderContext

The TopLoaderContext creates a React Context that allows useTopLoaderApi exposure.

TopLoaderProvider

The TopLoaderProvider Component exposes the useTopLoaderApi state and functions and handles start, tick and stop of the TopLoader progress while navigating on a different page.

TopLoaderProviderProps

The Component accepts UseTopLoaderApiOptions and children.

Next.js Integration

If you're developing a Next.js web application with the App Router, this library exports some wrappers required for a better integration.

useRouter

Extends the Next.js router with top loader integration.

This hook wraps the Next.js router and triggers a top loader animation whenever a navigation action (push or replace) changes the current pathname. It exposes the standard router methods (back, forward, refresh, prefetch) along with the enhanced push and replace methods.

It's usage remain unchanged so please refer to the official useRouter documention for more information.

Usage examples

Basic usage

Customizing progress bar styles

Progress bar custom component

Navigating with Next.js App Router

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email [email protected] to disclose any security vulnerabilities.

Made with ☕