react-nano-loader

Tiny, SSR-safe top loading bar for React with NProgress-style control.

Install

npm install react-nano-loader

This package supports both ESM and CommonJS consumers. Use import for ESM and require() for CommonJS as needed.

Basic Usage

import { NanoProgress, useTopLoader } from 'react-nano-loader'

export default function App() {
  const loader = useTopLoader()

  const loadData = async () => {
    loader.start()
    try {
      await fetch('/api/data')
    } finally {
      loader.done()
    }
  }

  return (
    <>
      <NanoProgress loader={loader} color="#29d" height={3} />
      <button onClick={loadData}>Load data</button>
    </>
  )
}

Router-specific hooks

Use the right hook for the routing system in your app:

• React Router: useReactRouterTopLoader from react-nano-loader/react-router
• Next.js App Router: useNextAppRouterTopLoader from react-nano-loader/next
• Next.js Pages Router: useNextPagesRouterTopLoader from react-nano-loader/next

React Router Auto-Load

Use the data router APIs (createBrowserRouter + <RouterProvider />).

import { NanoProgress } from 'react-nano-loader'
import { useReactRouterTopLoader } from 'react-nano-loader/react-router'

export default function AppShell() {
  const loader = useReactRouterTopLoader({
    trickle: true,
    trickleSpeed: 200,
  })

  return <NanoProgress loader={loader} color="#29d" height={3} />
}

Next.js Auto-Load

Import from react-nano-loader/next.

App Router (app/)

Use this in a client component. It starts on internal link clicks, browser history navigation, and the helper methods returned by the hook.

'use client'

import { NanoProgress } from 'react-nano-loader'
import { useNextAppRouterTopLoader } from 'react-nano-loader/next'

export default function TopLoader() {
  const loader = useNextAppRouterTopLoader()

  return <NanoProgress loader={loader} color="#29d" height={3} />
}

For imperative navigation, prefer the hook helpers:

const loader = useNextAppRouterTopLoader()

loader.push('/dashboard')
loader.replace('/settings')
loader.refresh()

Pages Router (pages/)

This uses Next.js router events automatically.

import { NanoProgress } from 'react-nano-loader'
import { useNextPagesRouterTopLoader } from 'react-nano-loader/next'

export default function AppShell() {
  const loader = useNextPagesRouterTopLoader()

  return <NanoProgress loader={loader} color="#29d" height={3} />
}

Props

NanoProgress

• loader: return value from useTopLoader() or router hook
• color: bar color, default #29d
• height: bar height in px, default 3
• speed: transition speed (ms), default 200
• trickle: enable/disable trickle, default true
• trickleSpeed: trickle interval (ms), default 200
• minimum: initial progress, default 0.08
• finishDelay: delay before hide (ms), default 320
• easing: CSS easing, default ease
• showSpinner: show spinner, default false
• spinnerPosition: left or right, default right
• zIndex: z-index, default 9999
• shadow: toggle glow/shadow, default true

useTopLoader

• returns { progress, visible, start, done, set, reset }

useNextAppRouterTopLoader

• returns the loader API plus push, replace, back, forward, refresh

SSR Safety

No window or document access during render. Any DOM access is inside useEffect, so it won’t run on the server.

Author

Created by Sanish Vasudevan.

License

MIT