TanStack QueryのisPending・isLoading・isFetchingの違いを理解する

TanStack QueryのisPending・isLoading・isFetchingについて、違いはなんとなく理解しているものの、なぜこんなに似た状態が用意されているのか気になったので調べてみました。この記事では、statusとfetchStatusの仕組みから、それぞれの役割や違いを整理していきます。

isPending・isLoading・isFetchingの違い

まずは、それぞれの違いを簡単に整理します。

一言でまとめると、次のようになります。

• isPending: データがまだ利用できない状態
• isLoading: 初回データ取得中
• isFetching: 通信中（初回取得・再取得の両方を含む）

なぜこんなに似た状態があるのか？

これらは、TanStack Queryが内部で管理しているstatusとfetchStatusという2つの状態から導き出されています。

つまり、isPendingやisFetchingは「元となる状態」を分かりやすく扱えるようにした派生プロパティです。

そのため、まずはstatusとfetchStatusがそれぞれ何を表しているのかを見ていきます。

statusとは

statusは、クエリが保持しているデータの状態を表します。

取り得る値は次の3つです。

ここで重要なのは、statusは通信中かどうかを表しているわけではないという点です。

あくまで「データが利用できる状態なのか」「取得に失敗した状態なのか」といった、データそのものの状態を表しています。

次に、通信中かどうかを表すfetchStatusについて見ていきます。

fetchStatusとは

fetchStatusは、クエリの通信状態を表します。

取り得る値は次の3つです。

statusとの違いは、データではなく通信に着目していることです。

例えば、データの取得に成功したあとでも、バックグラウンドで再取得が始まればfetchStatusはfetchingになります。一方で、statusは引き続きsuccessのままです。

つまり、

• statusはデータの状態
• fetchStatusは通信の状態

という役割で分かれています。

isPending・isLoading・isFetchingはどのように導き出されるのか

ここまで見てきたように、TanStack Queryには

• status（データの状態）
• fetchStatus（通信の状態）

という2つの状態があります。

実は、isPending・isLoading・isFetchingはこれらから導き出される派生プロパティです。

isPendingとisFetchingは、それぞれstatusとfetchStatusをそのまま分かりやすくしたものです。

一方、isLoadingだけは少し特殊で、**「データがまだ利用できず、かつ通信中である」**場合にのみtrueになります。

そのため、例えばオフラインなどで通信が一時停止している場合は、

• status = 'pending'
• fetchStatus = 'paused'

となり、

• isPending = true
• isFetching = false
• isLoading = false

となります。

つまり、isLoadingは「初回ローディング中」を表現するための、より限定的な状態であることが分かります。

まとめ

isPending・isLoading・isFetchingは、それぞれ独立した状態ではなく、statusとfetchStatusから導き出される派生プロパティです。

• statusはデータの状態
• fetchStatusは通信の状態
• isPendingはstatusを分かりやすくしたもの
• isFetchingはfetchStatusを分かりやすくしたもの
• isLoadingは「データがまだ利用できず、かつ通信中」であることを表す

このように、まずstatusとfetchStatusの役割を理解すると、isPending・isLoading・isFetchingの違いも自然と理解しやすくなります。