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 |