Next.js

useRouter (app dir)

Use `useRouter` hook

Breaking Change

As of version 3.2.0, router push and replace methods now have only 2 parameters (href and options). You can modify your router calls as follows:

- router.push('/dashboard', { scroll: false }, { startPosition: 0.3 })
+ router.push('/dashboard', { scroll: false, startPosition: 0.3 })

The app directory router doesn't manage routes like the page directory router. So we need a custom router that extends the Next.js router and enables the progress bar.

Warning

The useRouter hook can only be used in the app directory. It will not work in the pages directory.

Import

import { useRouter } from '@bprogress/next/app';

Usage

See the Next.js useRouter hook documentation for more information.

const router = useRouter();

Options

useRouter(options?: RouterProgressOptions): AppRouterProgressInstance;
NameTypeDefaultDescription
showProgressbooleantrueShow the progress bar.
startPositionnumberundefinedThe start position of the progress bar.
disableSameURLbooleantrueDisable the progress bar when the URL is the same.
basePathstringundefinedThe base path if you use a basePath in your app.
i18nPathbooleanfalseTakes into account the first parameter of the URL (e.g. /en)
delaynumberundefinedThe delay before the progress bar starts.
stopDelaynumberundefinedThe delay before the progress bar stops.
customRouter() => AppRouterInstanceundefinedA custom router instance.

Note

By default, if you do not specify any options when calling a router method, the options defined during the initialization of the useRouter hook will be applied. However, if you provide specific options in the method call (push, replace, back, refresh), these will take precedence and override the default options set in the hook.

RouterProgressOptions

interface RouterProgressOptions {
  showProgress?: boolean;
  startPosition?: number;
  disableSameURL?: boolean;
  basePath?: string;
  i18nPath?: boolean;
  customRouter?: () => AppRouterInstance;
}

AppRouterProgressInstance

export interface AppRouterProgressInstance<
  ROpts = NavigateOptions,
  POtps = PrefetchOptions,
> {
  push(href: string, options?: CombinedRouterOptions<ROpts>): void;
  replace(href: string, options?: CombinedRouterOptions<ROpts>): void;
  prefetch(href: string, options?: POtps): void;
  back(options?: CombinedRouterOptions<ROpts>): void;
  refresh(options?: CombinedRouterOptions<ROpts>): void;
  forward(options?: CombinedRouterOptions<ROpts>): void;
}

CombinedRouterOptions

export type CombinedRouterOptions<ROpts> = ROpts & RouterActionsProgressOptions;

Methods

push

Usage

Pushes a new entry onto the history stack.

router.push('/about');

Types

router.push(url: string, options?:CombinedRouterOptions<ROpts>)

replace

Usage

Replaces the current entry on the history stack.

router.replace('/?counter=10');

Types

router.replace(url: string, options?: CombinedRouterOptions<ROpts>)

back

Usage

Goes back in the history stack.

router.back();

Types

router.back(options?: CombinedRouterOptions<ROpts>)

forward

Usage

Goes forward in the history stack.

router.forward();

Types

router.forward(options?: CombinedRouterOptions<ROpts>)

refresh

Usage

Refreshes the current page.

router.refresh();

Types

router.refresh(options?: CombinedRouterOptions<ROpts>)

Options

Usage

router.push('/about', { disableSameURL: true });
router.replace('/?counter=10', { disableSameURL: true });
router.back({ startPosition: 0.3 });
router.forward({ startPosition: 0.3 });
router.refresh({ startPosition: 0.3 });

Types

NameTypeDefaultDescription
showProgressbooleantrueShow the progress bar.
startPositionnumberundefinedThe start position of the progress bar.
disableSameURLbooleantrueDisable the progress bar when the URL is the same.
basePathstringundefinedThe base path if you use a basePath in your app.
i18nPathbooleanfalseTakes into account the first parameter of the URL (e.g. /en)
delaynumberundefinedThe delay before the progress bar starts.
stopDelaynumberundefinedThe delay before the progress bar stops.
...customRouterOptionsanyundefinedAny custom options for the router, by default we use the next NavigateOptions.

Note

The showProgress option set to false disables the progress bar. However, if you don't want to see the progress bar during a router action, we recommend you use the Next.js router directly.

RouterProgressOptions

interface RouterProgressOptions {
  showProgress?: boolean;
  startPosition?: number;
  disableSameURL?: boolean;
  basePath?: string;
  i18nPath?: boolean;
  delay?: number;
  stopDelay?: number;
}

Example with next-intl custom router

import { useRouter } from '@bprogress/next/app';
import { useRouter as useNextIntlRouter } from '@/i18n/navigation';
 
export default function Home() {
  const router = useRouter({
    customRouter: useNextIntlRouter,
  });
 
  return (
    <button
      onClick={() =>
        router.push('/about', {
          startPosition: 0.3,
          locale: 'en',
        })
      }
    >
      Go to about page
    </button>
  );
}

Previous

useProgress

Next

Disable progress

On this page