{"id":14957328,"url":"https://github.com/thesgj/nextjs-toploader","last_synced_at":"2025-05-13T21:11:49.008Z","repository":{"id":114469379,"uuid":"609704465","full_name":"TheSGJ/nextjs-toploader","owner":"TheSGJ","description":"A Next.js Top Loading Bar component made using nprogress, works with Next.js 15 , Next.js 14 and React.","archived":false,"fork":false,"pushed_at":"2025-03-25T21:15:10.000Z","size":1341,"stargazers_count":1030,"open_issues_count":42,"forks_count":59,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-11T08:04:00.640Z","etag":null,"topics":["next","next13","next14","nextjs","nextjs13","nextjs14","progressbar","react","toploader"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/nextjs-toploader","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheSGJ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"thesgj","thanks_dev":"thesgj","buy_me_a_coffee":"thesgj","open_collective":"nextjs-toploader"}},"created_at":"2023-03-05T01:11:44.000Z","updated_at":"2025-05-10T02:59:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"5f7d4d28-6bfd-4450-94d9-b5ff846a45f9","html_url":"https://github.com/TheSGJ/nextjs-toploader","commit_stats":{"total_commits":80,"total_committers":19,"mean_commits":"4.2105263157894735","dds":"0.32499999999999996","last_synced_commit":"461a78d7704939d8f72f1a02263e3e0adf0432c3"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSGJ%2Fnextjs-toploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSGJ%2Fnextjs-toploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSGJ%2Fnextjs-toploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSGJ%2Fnextjs-toploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheSGJ","download_url":"https://codeload.github.com/TheSGJ/nextjs-toploader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254029004,"owners_count":22002283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["next","next13","next14","nextjs","nextjs13","nextjs14","progressbar","react","toploader"],"created_at":"2024-09-24T13:14:42.190Z","updated_at":"2025-05-13T21:11:48.967Z","avatar_url":"https://github.com/TheSGJ.png","language":"TypeScript","funding_links":["https://github.com/sponsors/thesgj","https://thanks.dev/thesgj","https://buymeacoffee.com/thesgj","https://opencollective.com/nextjs-toploader","https://github.com/sponsors/TheSGJ","https://www.buymeacoffee.com/thesgj"],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://images.opencollective.com/nextjs-toploader/070e1d1/logo/256.png?height=256\" alt=\"NextJS TopLoader\" width=\"50\" height=\"50\" style=\"vertical-align:middle; margin-right:10px\"/\u003e Next Js TopLoader\n\n- A Next.js Top Loading Bar component made using nprogress, works with Next.js 14 and React.\n\n[![NPM](https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge\u0026logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/nextjs-toploader)\n[![NPM Downloads](https://img.shields.io/npm/dm/nextjs-toploader?\u0026style=flat-square)](https://www.npmjs.com/package/nextjs-toploader)\n\n## Install\n\nusing npm:\n\n```bash\nnpm install nextjs-toploader\n```\n\nusing yarn:\n\n```bash\nyarn add nextjs-toploader\n```\n\n## Usage\n\nimport using:\n\n```js\nimport NextTopLoader from 'nextjs-toploader';\n```\n\n### Usage with `app/layout.js` for `app` folder structure\n\nFor rendering add `\u003cNextTopLoader /\u003e` to your `return()` inside the `\u003cbody\u003e\u003c/body\u003e` of `RootLayout()`:\n\n```js\nimport NextTopLoader from 'nextjs-toploader';\n\nexport default function RootLayout({ children }) {\n  return (\n    \u003chtml lang=\"en\"\u003e\n      \u003cbody\u003e\n        \u003cNextTopLoader /\u003e\n        {children}\n      \u003c/body\u003e\n    \u003c/html\u003e\n  );\n}\n```\n\n### Usage with `pages/_app.js` for `pages` folder structure\n\nFor rendering add `\u003cPagesTopLoader /\u003e` to your `return()` in `MyApp()` (Recommended):\n\n```js\nimport { PagesTopLoader } from 'nextjs-toploader/pages';\n\nexport default function MyApp({ Component, pageProps }) {\n  return (\n    \u003c\u003e\n      \u003cPagesTopLoader /\u003e\n      \u003cComponent {...pageProps} /\u003e;\n    \u003c/\u003e\n  );\n}\n```\n\nYou can also use `\u003cNextTopLoader /\u003e` in `pages` router, but it's recommended to use `\u003cPagesTopLoader /\u003e` for `useRouter` hook support from `nextjs-toploader` version 2.6.12 onwards\n\n## Compatibility with `useRouter` hook\n\n### `useRouter` hook usage with `app/layout.js` for `app` folder structure\n\nFor triggering TopLoader when using `useRouter` hook (app router):\n\n```js\n// Import the useRouter hook from nextjs-toploader to trigger the TopLoader\n\nimport { useRouter } from 'nextjs-toploader/app';\n```\n\nThen simply use it in your code for example:\n\n```js\nconst router = useRouter();\nrouter.push('/some-page');\n```\n\n### `useRouter` hook usage with `pages/_app.js` for `pages` folder structure\n\nFor triggering TopLoader when using `useRouter` add `\u003cPagesTopLoader /\u003e` to your `return()` in `MyApp()` :\n\n```js\nimport { PagesTopLoader } from 'nextjs-toploader/pages';\n\nexport default function MyApp({ Component, pageProps }) {\n  return (\n    \u003c\u003e\n      \u003cPagesTopLoader /\u003e\n      \u003cComponent {...pageProps} /\u003e;\n    \u003c/\u003e\n  );\n}\n```\n\n---\n\n## useTopLoader Hook\n\nA custom hook for handling progress indicators using NextTopLoader.\n\n## Methods\n\n| Name              | Description                                                                                                        |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------ |\n| start             | Starts the progress bar                                                                                            |\n| done              | Completes the progress bar. Can be forced to complete immediately with an optional force parameter                 |\n| remove            | Removes the progress bar element from the DOM                                                                      |\n| setProgress       | Manually sets the progress value (between 0.0 and 1.0)                                                             |\n| inc               | Increments the progress bar by a specified amount. If no amount is specified, it makes a small automatic increment |\n| trickle           | Adds small random increments to the progress bar                                                                   |\n| isStarted         | Checks if the progress bar has been started                                                                        |\n| isRendered        | Checks if the progress bar is rendered in the DOM                                                                  |\n| getPositioningCSS | Returns the positioning CSS property of the progress bar                                                           |\n\n## Example Usage\n\n```js\n'use client';\n\nimport React from 'react';\nimport { useTopLoader } from 'nextjs-toploader';\n\nconst Component = () =\u003e {\n  const loader = useTopLoader();\n  return (\n    \u003cdiv\u003e\n      \u003cbutton type=\"button\" onClick={() =\u003e loader.start()}\u003e\n        Start\n      \u003c/button\u003e\n      \u003cbutton type=\"button\" onClick={() =\u003e loader.setProgress(0.5)}\u003e\n        Set Progress\n      \u003c/button\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default Component;\n```\n\n---\n\n### Usage with React, Vite React or any other React Based Framework\n\nFor rendering add `\u003cNextTopLoader /\u003e` to your `return()` inside the \u003cRouter\u003e\u003cRouter/\u003e component in `App()` in your App.js:\n\n```js\nimport NextTopLoader from 'nextjs-toploader';\nconst App = () =\u003e {\n  return (\n    \u003cdiv\u003e\n      \u003cRouter\u003e\n        \u003cNextTopLoader /\u003e\n        \u003cRoutes\u003e{/* Your Routes Here */}\u003c/Routes\u003e\n      \u003c/Router\u003e\n    \u003c/div\u003e\n  );\n};\n\nexport default App;\n```\n\n### Default Configuration\n\nIf no props are passed to `\u003cNextTopLoader /\u003e`, below is the default configuration applied.\n\n```jsx\n\u003cNextTopLoader\n  color=\"#2299DD\"\n  initialPosition={0.08}\n  crawlSpeed={200}\n  height={3}\n  crawl={true}\n  showSpinner={true}\n  easing=\"ease\"\n  speed={200}\n  shadow=\"0 0 10px #2299DD,0 0 5px #2299DD\"\n  template='\u003cdiv class=\"bar\" role=\"bar\"\u003e\u003cdiv class=\"peg\"\u003e\u003c/div\u003e\u003c/div\u003e \n  \u003cdiv class=\"spinner\" role=\"spinner\"\u003e\u003cdiv class=\"spinner-icon\"\u003e\u003c/div\u003e\u003c/div\u003e'\n  zIndex={1600}\n  showAtBottom={false}\n/\u003e\n```\n\n- `color`: to change the default color of TopLoader.\n- `initialPosition`: to change initial position for the TopLoader in percentage, : `0.08 = 8%`.\n- `crawlSpeed`: increment delay speed in `ms`.\n- `speed`: animation speed for the TopLoader in `ms`\n- `easing`: animation settings using easing (a CSS easing string).\n- `height`: height of TopLoader in `px`.\n- `crawl`: auto incrementing behavior for the TopLoader.\n- `showSpinner`: to show spinner or not.\n- `shadow`: a smooth shadow for the TopLoader. (set it to `false` to disable it)\n- `template`: to include custom HTML attributes for the TopLoader.\n- `zIndex`: defines zIndex for the TopLoader.\n- `showAtBottom`: To show the TopLoader at bottom. (increase height for the TopLoader to ensure it's visibility at the mobile devices)\n- `showForHashAnchor`: To show for \"#\" url or not. (set it to `false` to disable it)\n\n#### `NextTopLoaderProps` (props passed to the TopLoader)\n\n| **Name**            | **Type**          | **Default Value**                                                                                                                       |\n| ------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `color`             | `string`          | `\"#2299DD\"`                                                                                                                             |\n| `initialPosition`   | `number`          | `0.08`                                                                                                                                  |\n| `crawlSpeed`        | `number`          | `200`                                                                                                                                   |\n| `height`            | `number`          | `3`                                                                                                                                     |\n| `crawl`             | `boolean`         | `true`                                                                                                                                  |\n| `showSpinner`       | `boolean`         | `true`                                                                                                                                  |\n| `easing`            | `string`          | `\"ease\"`                                                                                                                                |\n| `speed`             | `number`          | `200`                                                                                                                                   |\n| `shadow`            | `string \\| false` | `\"0 0 10px #2299DD,0 0 5px #2299DD\"`                                                                                                    |\n| `template`          | `string`          | `\"\u003cdiv class=\"bar\" role=\"bar\"\u003e\u003cdiv class=\"peg\"\u003e\u003c/div\u003e\u003c/div\u003e\u003cdiv class=\"spinner\" role=\"spinner\"\u003e\u003cdiv class=\"spinner-icon\"\u003e\u003c/div\u003e\u003c/div\u003e\"` |\n| `zIndex`            | `number`          | `1600`                                                                                                                                  |\n| `showAtBottom`      | `boolean`         | `false`                                                                                                                                 |\n| `showForHashAnchor` | `boolean`         | `true`                                                                                                                                  |\n\n## Contributors\n\n### Code Contributors\n\nThis project was made possible thanks to the contributions of its code contributors.\n\n\u003cimg src=\"https://opencollective.com/nextjs-toploader/contributors.svg?width=890\u0026button=false\" /\u003e\n\n### Financial Contribution\n\n---\n\nUPI ID: thesgj@upi (International UPI ID)\n\n[![Sponsor me on GitHub](https://img.shields.io/badge/Sponsor%20me%20on-GitHub-brightgreen)](https://github.com/sponsors/TheSGJ)\n\n[![\"Buy Me A Coffee\"](https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/thesgj)\n\n[![OpenCollective](https://opencollective.com/webpack/donate/button.png?color=blue)](https://opencollective.com/nextjs-toploader)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesgj%2Fnextjs-toploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthesgj%2Fnextjs-toploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesgj%2Fnextjs-toploader/lists"}