useRouter

useRouter 훅을 사용하면 클라이언트 컴포넌트 내에서 프로그래밍 방식으로 라우트를 변경할 수 있습니다.

추천: useRouter를 사용해야 하는 특정 요구사항이 없다면 내비게이션에는 <Link> 컴포넌트를 사용하세요.

app/example-client-component.tsx

"use client";
 
import { useRouter } from "next/navigation";
 
export default function Page() {
  const router = useRouter();
 
  return (
    <button type="button" onClick={() => router.push("/dashboard")}>
      Dashboard
    </button>
  );
}

app/example-client-component.js

"use client";
 
import { useRouter } from "next/navigation";
 
export default function Page() {
  const router = useRouter();
 
  return (
    <button type="button" onClick={() => router.push("/dashboard")}>
      Dashboard
    </button>
  );
}

`useRouter()`

router.push(href: string, { scroll: boolean }): 제공된 라우트로 클라이언트 사이드 내비게이션을 수행합니다. 브라우저의 히스토리 스택에 새 항목을 추가합니다.
router.replace(href: string, { scroll: boolean }): 브라우저의 히스토리 스택에 새 항목을 추가하지 않고 제공된 라우트로 클라이언트 사이드 내비게이션을 수행합니다.
router.refresh(): 현재 라우트를 새로고침합니다. 서버에 새 요청을 보내고, 데이터 요청을 다시 가져오며, 서버 컴포넌트를 다시 렌더링합니다. 클라이언트는 영향을 받지 않는 클라이언트 사이드 React (예: useState) 또는 브라우저 상태 (예: 스크롤 위치)를 잃지 않고 업데이트된 React 서버 컴포넌트 페이로드를 병합합니다.
router.prefetch(href: string): 더 빠른 클라이언트 사이드 전환을 위해 제공된 라우트를 프리페치합니다.
router.back(): 브라우저의 히스토리 스택에서 이전 라우트로 이동합니다.
router.forward(): 브라우저의 히스토리 스택에서 다음 페이지로 이동합니다.

알아두면 좋은 점:

<Link> 컴포넌트는 뷰포트에 보이게 되면 자동으로 라우트를 프리페치합니다.

refresh()는 fetch 요청이 캐시된 경우 동일한 결과를 다시 생성할 수 있습니다. cookies와 headers와 같은 다른 동적 함수도 응답을 변경할 수 있습니다.

`next/router`에서 마이그레이션

App Router를 사용할 때 useRouter 훅은 next/router가 아닌 next/navigation에서 가져와야 합니다.
pathname 문자열이 제거되고 usePathname()으로 대체되었습니다.
query 객체가 제거되고 useSearchParams()로 대체되었습니다.
router.events가 대체되었습니다. 아래를 참조하세요.

전체 마이그레이션 가이드 보기.

예시

라우터 이벤트

usePathname과 useSearchParams와 같은 다른 클라이언트 컴포넌트 훅을 구성하여 페이지 변경을 감지할 수 있습니다.

app/components/navigation-events.js

"use client";
 
import { useEffect } from "react";
import { usePathname, useSearchParams } from "next/navigation";
 
export function NavigationEvents() {
  const pathname = usePathname();
  const searchParams = useSearchParams();
 
  useEffect(() => {
    const url = `${pathname}?${searchParams}`;
    console.log(url);
    // 이제 현재 URL을 사용할 수 있습니다
    // ...
  }, [pathname, searchParams]);
 
  return "...";
}

이를 레이아웃에 가져올 수 있습니다.

app/layout.js

import { Suspense } from "react";
import { NavigationEvents } from "./components/navigation-events";
 
export default function Layout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
 
        <Suspense fallback={null}>
          <NavigationEvents />
        </Suspense>
      </body>
    </html>
  );
}

알아두면 좋은 점: <NavigationEvents>는 Suspense 경계로 감싸져 있습니다. 이는 useSearchParams()가 정적 렌더링 중에 가장 가까운 Suspense 경계까지 클라이언트 사이드 렌더링을 유발하기 때문입니다. 자세히 알아보기.

스크롤 복원 비활성화

기본적으로 Next.js는 새 라우트로 이동할 때 페이지의 맨 위로 스크롤합니다. router.push() 또는 router.replace()에 scroll: false를 전달하여 이 동작을 비활성화할 수 있습니다.

app/example-client-component.tsx

"use client";
 
import { useRouter } from "next/navigation";
 
export default function Page() {
  const router = useRouter();
 
  return (
    <button
      type="button"
      onClick={() => router.push("/dashboard", { scroll: false })}
    >
      Dashboard
    </button>
  );
}

app/example-client-component.jsx

"use client";
 
import { useRouter } from "next/navigation";
 
export default function Page() {
  const router = useRouter();
 
  return (
    <button
      type="button"
      onClick={() => router.push("/dashboard", { scroll: false })}
    >
      Dashboard
    </button>
  );
}

버전 기록

버전	변경사항
`v13.0.0`	`next/navigation`의 `useRouter` 도입됨.

useReportWebVitals useSearchParams