useLinkStatus

useLinkStatus は、ナビゲーション中の Link コンポーネントの読み込み状態を追跡できる**クライアントコンポーネント**のフックです。特にプリフェッチが無効になっている場合や、リンクされたルートに読み込み状態がない場合に、ページ遷移中に読み込みインジケータを表示するために使用できます。

app/loading-indicator.tsx

'use client'
 
import { useLinkStatus } from 'next/link'
 
export default function LoadingIndicator() {
  const { pending } = useLinkStatus()
  return pending ? <span>⌛</span> : null
}

app/header.tsx

import Link from 'next/link'
import LoadingIndicator from './loading-indicator'
 
export default function Header() {
  return (
    <header>
      <Link href="/dashboard" prefetch={false}>
        Dashboard <LoadingIndicator />
      </Link>
    </header>
  )
}

知っておくと良いこと:

useLinkStatus は Link コンポーネントの子孫コンポーネント内で使用する必要があります。

このフックは、Link コンポーネントに prefetch={false} が設定されている場合に最も役立ちます。

リンクされたルートがプリフェッチされている場合、保留状態はスキップされます。

複数のリンクを素早く連続してクリックした場合、最後のリンクの保留状態のみが表示されます。

このフックはPages Routerではサポートされておらず、常に { pending: false } を返します。

パラメータ

const { pending } = useLinkStatus()

useLinkStatus はパラメータを取りません。

戻り値

useLinkStatus は単一のプロパティを持つオブジェクトを返します。

プロパティ	型	説明
pending	boolean	履歴が更新される前は `true`、更新後は `false`。

例

新しいクエリパラメータでナビゲートする際のユーザーエクスペリエンスの向上

この例では、カテゴリ間を移動するとクエリ文字列が更新されます（例：?category=books）。しかし、<PageSkeleton />のフォールバックが既存のコンテンツを置き換えないため、ページが応答しないように見える場合があります（意図しないローディングインジケータの表示を防ぐを参照）。

useLinkStatusフックを使用すると、アクティブなリンクの隣に軽量なローディングインジケータを表示し、データがフェッチされている間、ユーザーに即座にフィードバックを提供できます。

app/components/loading-indicator.tsx

'use client'
 
import { useLinkStatus } from 'next/link'
 
export default function LoadingIndicator() {
  const { pending } = useLinkStatus()
  return pending ? <span>⌛</span> : null
}

app/page.tsx

import { useSearchParams } from 'next/navigation'
import Link from 'next/link'
import { Suspense } from 'react'
import LoadingIndicator from './loading-indicator'
 
function MenuBar() {
  return (
    <div>
      <Link href="?category=electronics">
        Electronics <LoadingIndicator />
      </Link>
      <Link href="?category=clothing">
        Clothing <LoadingIndicator />
      </Link>
      <Link href="?category=books">
        Books <LoadingIndicator />
      </Link>
    </div>
  )
}
 
async function ProductList({ category }: { category: string }) {
  const products = await fetchProducts(category)
 
  return (
    <ul>
      {products.map((product) => (
        <li key={product}>{product}</li>
      ))}
    </ul>
  )
}
 
export default async function ProductCategories({
  searchParams,
}: {
  searchParams: Promise<{
    category: string
  }>
}) {
  const { category } = await searchParams
 
  return (
    <Suspense fallback={<PageSkeleton />}>
      <MenuBar />
      <ProductList category={category} />
    </Suspense>
  )
}

バージョン	変更点
`v15.3.0`	`useLinkStatus`が導入されました。