React SDK

The @proofofhuman/react SDK provides React components and hooks for embedding human review attestation workflows directly in your application.

Installation

npm install @proofofhuman/react

Provider setup

Wrap your app with ProofOfHumanProvider. It accepts either a reviewToken for live mode or runs in demo mode without one.

import { ProofOfHumanProvider } from "@proofofhuman/react";
import "@proofofhuman/react/styles.css";

// Live mode (connected to your API)
<ProofOfHumanProvider
  reviewToken="rt_abc123..."
  baseUrl="https://your-api.com"
>
  {children}
</ProofOfHumanProvider>

// Demo mode (no backend required)
<ProofOfHumanProvider mode="demo">
  {children}
</ProofOfHumanProvider>

Components

ReviewSession

The main component for running a human review. Tracks time spent, scroll depth, section acknowledgements, presence, and comments — then submits evidence when all criteria are met.

import { ReviewSession } from "@proofofhuman/react";

<ReviewSession
  reviewId="review_abc123"
  criteria={criteriaProfile}
  onComplete={(attestation) => {
    console.log("Attestation issued:", attestation.id);
    console.log("Signature:", attestation.signature);
  }}
  onError={(error) => console.error(error)}
>
  {/* Optional: custom document renderer */}
  <YourDocumentViewer />
</ReviewSession>

Props:

Prop	Type	Description
`reviewId`	`string`	The review session ID
`criteria`	`CriteriaProfile`	Requirements the reviewer must meet
`document`	`string`	Plain text document to display (if no children)
`children`	`ReactNode`	Custom document renderer
`onComplete`	`(attestation: Attestation) => void`	Called when attestation is issued
`onError`	`(error: Error) => void`	Called on error

AttestationCard

Displays a completed attestation with evidence summary and cryptographic details.

import { AttestationCard } from "@proofofhuman/react";

<AttestationCard attestation={attestation} />

ReviewStatus

A status badge for showing review state on documents.

import { ReviewStatus } from "@proofofhuman/react";

<ReviewStatus status="verified" label="Human Reviewed" />

Hooks

useReviewSession

Full control over the review lifecycle.

import { useReviewSession } from "@proofofhuman/react";

const { status, progress, attestation, submit, error } = useReviewSession({
  reviewId: "review_abc123",
  criteria: criteriaProfile,
  onComplete: (att) => console.log(att),
});

// progress.timeMet, progress.scrollMet, progress.allMet, etc.
// Call submit() when progress.allMet is true

useReviewProgress

Track review progress without managing the full session.

import { useReviewProgress } from "@proofofhuman/react";

const {
  timeMet, scrollMet, presenceMet, sectionsMet, commentMet,
  allMet, percentage, timeSpent, maxScroll,
  scrollRef, handleScroll, toggleSection, setComment,
} = useReviewProgress({
  requirements: criteriaProfile.requirements,
  active: true,
});

useAttestation

Verify an attestation by ID.

import { useAttestation } from "@proofofhuman/react";

const { verification, loading, error, refetch } = useAttestation("att_abc123");
// verification.valid, verification.signature_valid, verification.hash_valid

Types

interface CriteriaProfile {
  id: string;
  name: string;
  description: string;
  type: "medical" | "legal" | "financial" | "general" | "custom";
  requirements: {
    minTimeSeconds: number;
    fullScroll: boolean;
    requireComment: boolean;
    requireEdit: boolean;
    presenceVerification: boolean;
    sectionsToAcknowledge: string[];
  };
}

interface Attestation {
  id: string;
  reviewId: string;
  documentHash: string;
  evidenceHash: string;
  signature: string;
  timestamp: string;
  evidence: ReviewEvidence;
  criteria: CriteriaProfile;
  demo: boolean;
  verified: boolean;
}

React SDK

On this page