Firebase Realtime Database

Firebase Realtime Database is a cloud-hosted NoSQL database that lets you store and sync data between your users in realtime.

Before using these hooks, ensure your Firebase project has Realtime Database enabled and your app is initialized with a Database instance.

Setup

import { initializeApp } from "firebase/app";
import { getDatabase } from "firebase/database";

// Initialize your Firebase app
initializeApp({ ... });

// Get the Realtime Database instance
const database = getDatabase(app);

Importing

Hooks are exported from the database namespace:

import { useOnValueQuery } from "@tanstack-query-firebase/react/database";

Hooks accept DatabaseReference / Query values from ref() / query() and the Database instance from getDatabase() (obtained at app init, not wrapped by these hooks).

One-time reads

Use useGetQuery when you need a single read without a realtime listener:

import { ref } from "firebase/database";
import { useGetQuery } from "@tanstack-query-firebase/react/database";

function UserProfile({ uid }: { uid: string }) {
  const userRef = ref(database, `users/${uid}`);
  const { data: snapshot, isLoading, isError, error } = useGetQuery(userRef, {
    queryKey: ["database", "users", uid],
  });

  if (isLoading) return <p>Loading...</p>;
  if (isError) return <p>Error: {error.message}</p>;

  return <p>{snapshot?.val()?.name}</p>;
}

Realtime listeners

Use listener hooks such as useOnValueQuery and the useOnChild* hooks to subscribe to Realtime Database events. The first snapshot resolves the query; later snapshots update the TanStack Query cache.

import { ref } from "firebase/database";
import { useOnValueQuery } from "@tanstack-query-firebase/react/database";

function LiveScoreboard({ gameId }: { gameId: string }) {
  const scoreRef = ref(database, `games/${gameId}/score`);
  const { data: snapshot } = useOnValueQuery(scoreRef, {
    queryKey: ["database", "onValue", "games", gameId, "score"],
  });

  return <p>Score: {snapshot?.val() ?? 0}</p>;
}

Pass Firebase ListenOptions via the database option (for example { onlyOnce: true }):

useOnValueQuery(scoreRef, {
  queryKey: ["database", "onValue", "games", gameId, "score"],
  database: { onlyOnce: true },
});

Mutations

Write hooks follow the same pattern as other TanStack Query Firebase modules. Pass a DatabaseReference when creating the hook, then call mutate with the payload:

import { ref } from "firebase/database";
import { useSetMutation } from "@tanstack-query-firebase/react/database";

function UpdateUser({ uid }: { uid: string }) {
  const userRef = ref(database, `users/${uid}`);
  const { mutate, isPending } = useSetMutation(userRef);

  return (
    <button
      disabled={isPending}
      onClick={() => mutate({ name: "Ada", score: 1 })}
    >
      Save
    </button>
  );
}

Connection and on-disconnect hooks

• useGoOnlineMutation / useGoOfflineMutation accept a Database instance to control client connectivity.
• useOnDisconnect* hooks queue writes that run when the client disconnects from the Realtime Database server.

Available hooks

Queries

• useGetQuery — one-time read via get
• useOnValueQuery — subscribe to value changes
• useOnChildAddedQuery — subscribe to child_added
• useOnChildChangedQuery — subscribe to child_changed
• useOnChildMovedQuery — subscribe to child_moved
• useOnChildRemovedQuery — subscribe to child_removed

Mutations

• useSetMutation — replace data at a location
• useUpdateMutation — multi-path update
• useRemoveMutation — delete data
• usePushMutation — append with an auto-generated key
• useRunTransactionMutation — atomic read-modify-write
• useSetPriorityMutation — set node priority
• useSetWithPriorityMutation — write value and priority together
• useGoOnlineMutation — reconnect to the server
• useGoOfflineMutation — disconnect from the server
• useOnDisconnectSetMutation — queue a disconnect set
• useOnDisconnectUpdateMutation — queue a disconnect update
• useOnDisconnectRemoveMutation — queue a disconnect remove
• useOnDisconnectCancelMutation — cancel queued disconnect operations
• useOnDisconnectSetWithPriorityMutation — queue a disconnect setWithPriority