Authentication Hooks

Built-in Hooks

useReclaimAuth

The primary hook for accessing authentication functionality:

import { useReclaimAuth } from 'identity-react';
 
function Component() {
  const { user, signIn, signOut, loading, error } = useReclaimAuth();
  // ...
}

Returns

interface UseReclaimAuthReturn {
  user: ReclaimUser | null;
  loading: boolean;
  error: Error | null;
  signIn: () => Promise<void>;
  signOut: () => Promise<void>;
  getCurrentUser: () => ReclaimUser | null;
}

useAuthState

Hook for accessing only the authentication state:

import { useAuthState } from 'identity-react';
 
function Component() {
  const { user, loading } = useAuthState();
  // ...
}

useAuthActions

Hook for accessing authentication actions:

import { useAuthActions } from 'identity-react';
 
function Component() {
  const { signIn, signOut } = useAuthActions();
  // ...
}

Custom Hook Examples

useRequireAuth

Create a hook to enforce authentication:

function useRequireAuth(redirectUrl = '/login') {
  const { user, loading } = useReclaimAuth();
  const navigate = useNavigate();
 
  useEffect(() => {
    if (!loading && !user) {
      navigate(redirectUrl);
    }
  }, [user, loading, navigate, redirectUrl]);
 
  return { user, loading };
}

useAuthCallback

Handle authentication callbacks:

function useAuthCallback(onSuccess?: (user: ReclaimUser) => void) {
  const { signIn } = useReclaimAuth();
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState(false);
 
  const handleAuth = async () => {
    try {
      setLoading(true);
      setError(null);
      const user = await signIn();
      onSuccess?.(user);
    } catch (err) {
      setError(err instanceof Error ? err : new Error('Auth failed'));
    } finally {
      setLoading(false);
    }
  };
 
  return { handleAuth, error, loading };
}

Using Hooks with TypeScript

// Custom hook with proper typing
function useAuth<T extends ReclaimUser>() {
  const { user, ...rest } = useReclaimAuth();
  return {
    user: user as T | null,
    ...rest
  };
}
 
// Usage with custom user type
interface CustomUser extends ReclaimUser {
  data: {
    email: string;
    name: string;
    providerId: string;
  };
}
 
function Profile() {
  const { user } = useAuth<CustomUser>();
  
  if (user) {
    // TypeScript now knows about email, name, and providerId
    const { email, name, providerId } = user.data;
  }
}

API Reference Overview