Holy Loader is a lightweight and customizable top-loading progress bar component, specifically designed for React applications and optimized for Next.js with app router.
Want to see it in use? Visit: GameGator.
Also check out Holy Time, yet another (type-safe) date time library.
- Easy to integrate with any React application.
- Highly customizable with sensible defaults.
- Utilizes a custom implementation for smooth, aesthetic progress indications.
- Supports dynamic configuration for color, height, speed, easing, and more.
To install Holy Loader, run the following command in your project directory:
npm install holy-loaderOR
yarn add holy-loaderTo use Holy Loader in your Next.js application using the app router:
import HolyLoader from "holy-loader";
export default function RootLayout({ children }) {
return (
<html lang="en">
<HolyLoader />
{children}
</html>
);
}To use Holy Loader in your Next.js application using the pages router:
import HolyLoader from "holy-loader";
export default function App({ Component, pageProps }) {
return (
<>
<HolyLoader />
<Component {...pageProps} />;
</>
);
}import HolyLoader from "holy-loader";
export default function RootLayout({ children }) {
return (
<html lang="en">
<HolyLoader
color="#ff4500"
height="1rem"
speed={250}
easing="linear"
showSpinner
/>
{children}
</html>
);
}Have an async operation before an eventual route change? You might be interested in holy-loader's manual controls. These only work in client components!
'use client';
import { startHolyLoader, stopHolyLoader } from 'holy-loader';
try {
startHolyLoader(); // Trigger the loader beforehand
await signOut(); // Example async operation
} catch (error) {
stopHolyLoader(); // Stop the loader on error
// Handle the error
} finally {
stopHolyLoader(); // Stop the loader after the operation, and potentially do something else
/* OR */
router.push('/'); // Navigate to the desired route, which will automatically stop the loader
}Prevent triggering the loader when clicking a Button within a Next link:
onClick={(e) => {
e.preventDefault();
e.nativeEvent.stopImmediatePropagation();
}}<HolyLoader /> accepts the following props for customization:
-
color(string): Specifies the color of the top-loading bar. Default: "#59a2ff" (a shade of blue). -
initialPosition(number): Sets the initial position of the top-loading bar as a percentage of the total width. Default: 0.08 (8% of the total width). -
height(number | string): Defines the height of the top-loading bar in pixels or css unit. Default: 4 pixels. -
easing(string): Specifies the easing function to use for the loading animation. Accepts any valid CSS easing string. Default: "ease". -
speed(number): Sets the animation speed of the top-loading bar in milliseconds. Default: 200 milliseconds. -
zIndex(number): Defines the z-index property of the top-loading bar, controlling its stacking order. Default: 2147483647. -
boxShadow(string): Sets the box-shadow property of the top-loading bar. Turned off by default. -
showSpinner(boolean): Determines whether to accompany the loading bar with a spinner. Turned off by default.
Project inspired by nextjs-toploader & nprogress