useGalacha

The imperative hook. Returns the current Galacha state and the functions to control it.

Import

import { useGalacha } from "@galacha/react";

Basic usage

function StatusBar() {
  const { ready, sessionId, visitorId } = useGalacha();
 
  return (
    <div>
      {ready ? "recording" : "loading…"} · session {sessionId ?? "—"}
    </div>
  );
}

Must be called inside a <GalachaProvider>. Throws at runtime if the Provider is missing.

Return shape

interface GalachaContextValue {
  ready: boolean;
  identify: (userId: string, traits?: GalachaTraits) => void;
  stop: () => void;
  sessionId: string | null;
  visitorId: string | null;
}
FieldTypePurpose
readybooleantrue once the SDK has booted and init() has run
identifyfunctionTag the current session with a user identity. Buffered if called before ready
stopfunctionTear down recording, flush the buffer
sessionIdstring | nullCurrent session ID
visitorIdstring | nullPersistent anonymous visitor ID

Identifying a user

function LoginForm() {
  const { identify } = useGalacha();
 
  const handleSubmit = async (email: string, password: string) => {
    const user = await api.login(email, password);
    identify(user.id, {
      email: user.email,
      name: user.name,
      plan: user.plan,
    });
  };
 
  return <form onSubmit={/* ... */} />;
}

Two positional arguments: string user ID, optional traits. See Identifiers for what makes a good user ID.

If you identify before the Provider has finished loading the SDK (e.g., during a very early render), the call is buffered in memory and replayed as soon as the SDK is ready. No events are lost.

Stopping recording

function LogoutButton() {
  const { stop } = useGalacha();
 
  const handleLogout = () => {
    stop();
    // ... clear tokens, redirect
  };
 
  return <button onClick={handleLogout}>Log out</button>;
}

Heads up: stop() is a one-way trip. Once called, recording pauses until the page reloads or the Provider unmounts and remounts. For most logout flows, skip the stop call and let the next identify() retag the session.

Reading session state in a debug panel

function DevTools() {
  const { ready, sessionId, visitorId } = useGalacha();
 
  if (process.env.NODE_ENV === "production") return null;
 
  return (
    <div className="fixed bottom-4 right-4 bg-black text-white p-2 rounded text-xs">
      <div>Galacha: {ready ? "✅" : "⏳"}</div>
      <div>Session: {sessionId?.slice(0, 12)}…</div>
      <div>Visitor: {visitorId?.slice(0, 12)}…</div>
    </div>
  );
}

Common patterns

Identify after login, reset on logout

function AppShell() {
  const { user } = useAuth();
  const { identify } = useGalacha();
 
  useEffect(() => {
    if (user) {
      identify(user.id, { email: user.email });
    }
  }, [user?.id, identify]);
 
  return <Routes />;
}

Declarative version (cleaner)

Use useIdentify instead of wiring up the effect yourself.

Attaching session ID to error reports

const { sessionId } = useGalacha();
 
Sentry.setContext("galacha", { sessionId });

Pairs Galacha replays with Sentry error reports — click a Sentry issue, grab the session ID, paste into the Galacha dashboard search.

Throws if Provider is missing

// ❌ Missing Provider
function Orphan() {
  const { ready } = useGalacha();
  // → throws: "useGalacha must be used inside <GalachaProvider>"
}

Wrap a common ancestor in <GalachaProvider> — usually your root layout. See GalachaProvider.

Related