Hooks

In-depth hooks reference: data fetching and mutations, cache behavior, auth/session hooks, and common usage patterns for the Humanity React SDK.

All hooks must be called inside a component that is a descendant of HumanityProvider. Calling them outside will throw an error.

---

TypeScript Types

All types are exported directly from @humanity-org/react-sdk:

// Auth
type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
type Environment = 'production' | 'sandbox';
type StorageStrategy = 'memory' | 'localStorage' | 'sessionStorage';
type OAuthMode = 'popup' | 'redirect';

// User profile (returned after login)
interface UserProfile {
  sub: string;             // Unique user ID
  email?: string;
  name?: string;
  humanity_score?: number;
  // Additional fields depending on granted scopes
}

// Auth operation result
interface AuthResult {
  user: UserProfile;
  accessToken: string;
}

// Verification result
interface VerificationResult {
  preset: string;
  verified: boolean;
  status: 'valid' | 'expired' | 'pending' | 'unavailable';
  expiresAt?: string;
}

type PresetStatus = 'valid' | 'expired' | 'pending' | 'unavailable';

useHumanity()

Full-access hook to the entire SDK context. Includes both auth state and verification operations.

import { useHumanity } from '@humanity-org/react-sdk';

function MyComponent() {
  const {
    user,
    accessToken,
    authStatus,
    isAuthenticated,
    isLoading,
    error,
    login,
    logout,
    refreshToken,
    verify,
    verifyMultiple,
  } = useHumanity();
}

ℹ️ Note: For most use cases, prefer the focused hooks below (useAuth, useVerification) — they select only what they need and avoid unnecessary re-renders.

---

Returns

Field	Type	Description
user	HumanityUser	null
accessToken	string	null
authStatus	'idle'	'loading'
isAuthenticated	boolean	true when the user is authenticated.
isLoading	boolean	true while an auth or verification request is in-flight.
error	HumanityReactError	null
login	() => Promise	Initiate the login flow.
logout	() => void	Log out and clear the session.
refreshToken	() => Promise	Manually refresh the access token.
verify	(preset: string) => Promise	Verify a single preset.
verifyMultiple	(presets: string[]) => Promise<VerificationResult[]>	Verify multiple presets at once.

useAuth()

Auth-focused hook. Selects only authentication state and operations from the context.

import { useAuth } from '@humanity-org/react-sdk';

function LoginButton() {
  const { isAuthenticated, login, logout, isLoading } = useAuth();

  if (isLoading) return <Spinner />;
  if (isAuthenticated) return <button onClick={logout}>Sign Out</button>;
  return <button onClick={() => login()}>Sign In</button>;
}

Returns

Field	Type	Description
isAuthenticated	boolean	true when the user is authenticated.
isLoading	boolean	true while an auth request is in-flight.
login	() => Promise	Initiate the login flow.
logout	() => void	Log out and clear the session.

useVerification()

Runs preset verifications against the Humanity Protocol API. Returns a discriminated union status for type-safe state narrowing.

import { useVerification } from '@humanity-org/react-sdk';

function AgeCheck() {
  const { verify, status, result, isLoading } = useVerification();

  return (
    <div>
      <button onClick={() => verify('ageOver21')} disabled={isLoading}>
        Check Age
      </button>
      {status === 'success' && (
        <p>{result.verified ? '✅ Verified' : '❌ Not verified'}</p>
      )}
      {status === 'error' && <p>Verification failed</p>}
    </div>
  );
}

Returns

Field	Type	Description
status	'idle' | 'loading' | 'success' | 'error'	Discriminated union status. Narrow with switch or if.
result	VerificationResult | null	Verification result when status === 'success'; null otherwise.
error	HumanityReactError | null	Error when status === 'error'; null otherwise.
isLoading	boolean	true while a request is in-flight.
verify	(preset: string) => Promise<VerificationResult>	Verify a single preset.
verifyMultiple	(presets: string[]) => Promise<VerificationResult[]>	Verify multiple presets at once.
reset	() => void	Reset to idle state.

---

usePresets()

Manages and caches multiple preset verifications. Stores results in an internal map for easy per-preset access. Ideal for dashboards that need to check several presets at once.

import { usePresets } from '@humanity-org/react-sdk';
import { useEffect } from 'react';

function Dashboard() {
  const { verifyAll, isVerified, getResult, isLoading } = usePresets();

  useEffect(() => {
    verifyAll(['ageOver18', 'kycPassed']);
  }, [verifyAll]);

  if (isLoading) return <Spinner />;

  return (
    <div>
      <p>Age 18+: {isVerified('ageOver18') ? '✅' : '❌'}</p>
      <p>KYC: {isVerified('kycPassed') ? '✅' : '❌'}</p>
    </div>
  );
}

Returns

Field	Type	Description
status	'idle' | 'loading' | 'success' | 'error'	Discriminated union status.
results	Map<string, VerificationResult>	Map of preset key → verification result.
error	HumanityReactError | null	Error when status === 'error'; null otherwise.
isLoading	boolean	true while a verification batch is in-flight.
verifyAll	(presets: string[]) => Promise<VerificationResult[]>	Verify a batch of presets; stores all results internally.
getResult	(preset: string) => VerificationResult | undefined	Get the cached result for a specific preset.
isVerified	(preset: string) => boolean	Quick check: is the given preset verified?
reset	() => void	Clear all stored results and reset to idle.

---

useCredentialUpdates()

Polls the Humanity Protocol API for credential updates. Useful for keeping verification status in sync without requiring a full page reload.

import { useCredentialUpdates } from '@humanity-org/react-sdk';

function CredentialDashboard() {
  const { data, isLoading, error, refetch } = useCredentialUpdates({
    pollInterval: 30_000, // poll every 30 seconds
    enabled: true,
  });

  if (isLoading && !data) return <Spinner />;
  if (error) return <p>Failed to load credentials</p>;

  return (
    <div>
      <p>Active credentials: {data?.credentials.length ?? 0}</p>
      <button onClick={refetch}>Refresh Now</button>
    </div>
  );
}

Options

Option	Type	Default	Description
pollInterval	number	0	Polling interval in milliseconds. 0 disables polling.
enabled	boolean	true	Whether polling is active.

Returns

Field	Type	Description
data	CredentialUpdates | null	Latest credential updates, or null.
isLoading	boolean	true while a request is in-flight.
error	HumanityReactError | null	Most recent error, or null.
refetch	() => Promise<void>	Manually trigger a fetch.

---