useIsMutating

01무엇

useIsMutating은 지금 실행 중인 뮤테이션의 개수를 돌려주는 훅이다. 하나라도 진행 중이면 0보다 큰 수가 나온다.

반환값은 숫자다. 앱 어딘가에서 뮤테이션이 돌고 있는지를 한 값으로 알고 싶을 때 쓴다. 전역 저장 표시나 로딩 바 같은 곳에 붙인다.

const isMutating = useIsMutating()

02무슨 일이 일어나나

React Query는 모든 뮤테이션을 MutationCache 한곳에서 관리한다. useIsMutating은 그 캐시를 구독하고, pending 상태인 뮤테이션의 수를 센다. 뮤테이션이 시작되거나 끝날 때마다 값이 바뀌고, 그 컴포넌트를 다시 그린다.

첫 번째 인자로 filters를 넘기면 세는 범위를 좁힐 수 있다. mutationKey로 특정 뮤테이션 계열만 세는 식이다.

// posts로 시작하는 뮤테이션만 센다
const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })

filters는 객체로 감싸지 않고 그대로 첫 인자에 넣는다. 두 번째 인자는 QueryClient이며, 생략하면 가장 가까운 provider의 것을 쓴다.

03사용법

값이 0인지 아닌지로 표시 여부를 정한다. 진행 중인 개수 자체를 화면에 보여줘도 된다.

import { useIsMutating } from '@tanstack/react-query'

export function GlobalSpinner() {
  const isMutating = useIsMutating()
  if (isMutating === 0) return null
  return <div className="spinner">저장 중… ({isMutating})</div>
}

04실무 예시

여러 폼이 동시에 저장될 수 있는 화면에서, 헤더에 "저장 중" 표시를 하나만 두는 경우다. 각 폼이 어떤 상태인지 일일이 넘겨받지 않고, 전역 개수만 본다.

import { useIsMutating } from '@tanstack/react-query'

export function Header() {
  const pending = useIsMutating()
  return (
    <header>
      <h1>대시보드</h1>
      {pending > 0 && <span>변경사항 저장 중…</span>}
    </header>
  )
}

05왜 중요한가

useIsMutating은 매일 쓰는 훅은 아니다. 개별 뮤테이션의 상태는 보통 useMutation이 돌려주는 isPending으로 충분하기 때문이다. 이 훅이 빛나는 건 뮤테이션이 여러 곳에 흩어져 있고, 그중 하나라도 진행 중인지를 한군데서 알아야 할 때다. 전역 로딩 표시나 "저장 안 됨" 경고처럼 앱 전체를 훑는 UI에 잘 맞는다.

Reference