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.
- Manual controls: Start & stop the loader yourself.
- i18n ready: Supports
ltr(left-to-right) &rtl(right-to-left) layouts with thedirprop.
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="linear-gradient(to right, #ff7e5f, #feb47b)"
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();
await signOut()
} catch (error) {
stopHolyLoader();
} finally {
stopHolyLoader();
/* OR */
router.push('/');
}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:
| Prop | Type | Description | Default |
|---|---|---|---|
color |
string |
Specifies the color of the top-loading bar. Accepts any valid CSS background value, including gradients. |
#59a2ff |
initialPosition |
number |
Sets the initial position of the top-loading bar as a percentage of the total width. | 0.08 |
height |
number or string |
Defines the height of the top-loading bar in pixels or CSS unit. | 4px |
easing |
string |
Specifies the easing function to use for the loading animation. Accepts any valid CSS easing string. | ease |
speed |
number |
Sets the animation speed of the top-loading bar in milliseconds. | 200 |
zIndex |
number |
Defines the z-index property of the top-loading bar, controlling its stacking order. | 2147483647 |
boxShadow |
string |
Sets the box-shadow property of the top-loading bar. Turned off by default. | null |
showSpinner |
boolean |
Determines whether to accompany the loading bar with a spinner. Turned off by default. | false |
ignoreSearchParams |
boolean |
Determines whether to ignore search parameters in the URL when triggering the loader. Turned off by default. | false |
dir |
ltr or rtl |
Sets the direction of the top-loading bar. | ltr |