Run the following command to start using react-top-loader in your projects:
npm i @alessiofrittoli/react-top-loaderor using pnpm
pnpm i @alessiofrittoli/react-top-loaderProgress 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.
Displays a top loader progress while navigating on a different page.
This Component internally use the TopLoaderProvider Component in order to expose the useTopLoaderApi widely in your app.
Component Props
| 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.
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.
Component Props
| 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.
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.
Defines accepted properties in useTopLoaderApi options.
- onStart?:
OnStartHandler- A custom callback executed when thestartmethod is called. - onTick?:
OnTickHandler- A custom callback executed when the progress value is updated. - onStop?:
OnStopHandler- A custom callback executed when thestopmethod is called.
A custom callback executed when the start method is called.
() => voidA custom callback executed when the progress value is updated.
( progress: number ) => voidParameters
| Parameter | Type | Description |
|---|---|---|
progress |
number |
The progress value number from 0 to 100. |
A custom callback executed when the stop method is called.
() => voidHook parameters
| 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. |
Returns
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 to100and stop the TopLoader work.
Access to the TopLoader React Context API.
Returns
Type: UseTopLoaderApi
This hooks returns the useTopLoaderApi result exposed through the TopLoaderContext.
The TopLoaderContext creates a React Context that allows useTopLoaderApi exposure.
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.
Component Props
The Component accepts UseTopLoaderApiOptions and children.
If you're developing a Next.js web application with the App Router, this library exports some wrappers required for a better integration.
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.
npm installor using pnpm
pnpm iRun the following command to test and build code for distribution.
pnpm buildwarnings / errors check.
pnpm lintRun 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.jsonfile scripts for more info.
Run tests with coverage.
An HTTP server is then started to serve coverage files from ./coverage folder.
test:coverage:serveContributions 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.
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 security@alessiofrittoli.it to disclose any security vulnerabilities.
|
|