Merge pull request #114 from farukozdemirz/feature/use-top-loader-hook

feat: add useTopLoader hook for managing NextTopLoader

Author: TheSGJ

README.md

@@ -103,6 +103,51 @@ export default function MyApp({ Component, pageProps }) {
 
 ---
 
+## useTopLoader Hook
+
+A custom hook for handling progress indicators using NextTopLoader.
+
+## Methods
+
+| Name              | Description                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
+| start             | Starts the progress bar                                                                                            |
+| done              | Completes the progress bar. Can be forced to complete immediately with an optional force parameter                 |
+| remove            | Removes the progress bar element from the DOM                                                                      |
+| setProgress       | Manually sets the progress value (between 0.0 and 1.0)                                                             |
+| inc               | Increments the progress bar by a specified amount. If no amount is specified, it makes a small automatic increment |
+| trickle           | Adds small random increments to the progress bar                                                                   |
+| isStarted         | Checks if the progress bar has been started                                                                        |
+| isRendered        | Checks if the progress bar is rendered in the DOM                                                                  |
+| getPositioningCSS | Returns the positioning CSS property of the progress bar                                                           |
+
+## Example Usage
+
+```js
+'use client';
+
+import React from 'react';
+import { useTopLoader } from 'nextjs-toploader';
+
+const Component = () => {
+  const loader = useTopLoader();
+  return (
+    <div>
+      <button type="button" onClick={() => loader.start()}>
+        Start
+      </button>
+      <button type="button" onClick={() => loader.setProgress(0.5)}>
+        Set Progress
+      </button>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+---
+
 ### Usage with React, Vite React or any other React Based Framework
 
 For rendering add `<NextTopLoader />` to your `return()` inside the <Router><Router/> component in `App()` in your App.js:

src/hooks/useTopLoader.tsx

@@ -0,0 +1,29 @@
+import * as NProgress from 'nprogress';
+
+interface TopLoaderActions {
+  start: () => NProgress.NProgress;
+  done: (force?: boolean) => NProgress.NProgress;
+  remove: () => void;
+  setProgress: (value: number) => NProgress.NProgress;
+  inc: (amount?: number) => NProgress.NProgress;
+  trickle: () => NProgress.NProgress;
+  isStarted: () => boolean;
+  isRendered: () => boolean;
+  getPositioningCSS: () => "translate3d" | "translate" | "margin";
+}
+
+export const useTopLoader = (): TopLoaderActions => {
+  const actions: TopLoaderActions = {
+    start: () => NProgress.start(),
+    done: (force?: boolean) => NProgress.done(force),
+    remove: () => NProgress.remove(),
+    setProgress: (value: number) => NProgress.set(value),
+    inc: (amount?: number) => NProgress.inc(amount),
+    trickle: () => NProgress.trickle(),
+    isStarted: () => NProgress.isStarted(),
+    isRendered: () => NProgress.isRendered(),
+    getPositioningCSS: () => NProgress.getPositioningCSS(),
+  };
+
+  return actions;
+};

src/index.tsx

@@ -7,6 +7,7 @@
 import * as PropTypes from 'prop-types';
 import * as React from 'react';
 import * as NProgress from 'nprogress';
+export { useTopLoader } from './hooks/useTopLoader';
 
 // @deno-types ="npm:preact@10.19.6"