useRouter
TheuseRouter hook allows you to programmatically change routes insideClient Components.
Recommendation: Use the
<Link>component for navigation unless you have a specific requirement for usinguseRouter.
'use client'import { useRouter }from'next/navigation'exportdefaultfunctionPage() {constrouter=useRouter()return ( <buttontype="button"onClick={()=>router.push('/dashboard')}> Dashboard </button> )}useRouter()
router.push(href: string, { scroll: boolean }): Perform a client-side navigation to the provided route. Adds a new entry into thebrowser's history stack.router.replace(href: string, { scroll: boolean }): Perform a client-side navigation to the provided route without adding a new entry into the browser’s history stack.router.refresh(): Refresh the current route. Making a new request to the server, re-fetching data requests, and re-rendering Server Components. The client will merge the updated React Server Component payload without losing unaffected client-side React (e.g.useState) or browser state (e.g. scroll position).router.prefetch(href: string, options?: { onInvalidate?: () => void }):Prefetch the provided route for faster client-side transitions. The optionalonInvalidatecallback is called when theprefetched data becomes stale.router.back(): Navigate back to the previous route in the browser’s history stack.router.forward(): Navigate forwards to the next page in the browser’s history stack.
Good to know:
- You must not send untrusted or unsanitized URLs to
router.pushorrouter.replace, as this can open your site to cross-site scripting (XSS) vulnerabilities. For example,#"">Migrating fromnext/router
- The
useRouterhook should be imported fromnext/navigationand notnext/routerwhen using the App Router- The
pathnamestring has been removed and is replaced byusePathname()- The
queryobject has been removed and is replaced byuseSearchParams()router.eventshas been replaced.See below.View the full migration guide.
Examples
Router events
You can listen for page changes by composing other Client Component hooks like
usePathnameanduseSearchParams.app/components/navigation-events.js'use client'import { useEffect }from'react'import { usePathname, useSearchParams }from'next/navigation'exportfunctionNavigationEvents() {constpathname=usePathname()constsearchParams=useSearchParams()useEffect(()=> {consturl=`${pathname}?${searchParams}`console.log(url)// You can now use the current URL// ... }, [pathname, searchParams])return'...'}Which can be imported into a layout.
app/layout.jsimport { Suspense }from'react'import { NavigationEvents }from'./components/navigation-events'exportdefaultfunctionLayout({ children }) {return ( <htmllang="en"> <body> {children} <Suspensefallback={null}> <NavigationEvents /> </Suspense> </body> </html> )}Good to know:
<NavigationEvents>is wrapped in aSuspenseboundary becauseuseSearchParams()causes client-side rendering up to the closestSuspenseboundary duringstatic rendering.Learn more.Disabling scroll to top
By default, Next.js will scroll to the top of the page when navigating to a new route. You can disable this behavior by passing
scroll: falsetorouter.push()orrouter.replace().app/example-client-component.tsx'use client'import { useRouter }from'next/navigation'exportdefaultfunctionPage() {constrouter=useRouter()return ( <buttontype="button"onClick={()=>router.push('/dashboard', { scroll:false })} > Dashboard </button> )}Version History
Version Changes v15.4.0Optional onInvalidatecallback forrouter.prefetchintroducedv13.0.0useRouterfromnext/navigationintroduced.
Was this helpful?