React

@personablocks/react wraps the vanilla Web SDK for React apps: the usePersonaBlocks hook manages the SDK instance’s lifecycle for you, and the <PersonaBlocksVerify> component gives you a drop-in element when you’d rather not touch the imperative API at all.

Both share the same configuration and callback shape as the vanilla SDK, so switching between them — or falling back to the hook for cases the component doesn’t cover — doesn’t change how your app talks to a session.

Install

npm install @personablocks/react @personablocks/kyc-sdk react

@personablocks/react lists react as a peer dependency (^18 || ^19) and builds on @personablocks/kyc-sdk, so install all three together.

<PersonaBlocksVerify>

The component mounts a verification instance into a container <div>, auto-opens it once ready, and tears it down on unmount or whenever clientToken/flow change.

import { PersonaBlocksVerify } from '@personablocks/react';

function CheckoutKyc({ clientToken }: { clientToken: string }) {
  return (
    <PersonaBlocksVerify
      clientToken={clientToken}
      flow="auto"
      appearance={{ theme: 'light' }}
      onComplete={({ sessionId, vicId, method }) => {
        // IDs only — verdict/tier data is a server-to-server (webhook) concern.
        console.log('verified', { sessionId, vicId, method });
      }}
      onError={({ type, recoverable, message }) => {
        console.error('PersonaBlocks error', type, recoverable, message);
      }}
      style={{ minHeight: 480 }}
    >
      Loading verification…
    </PersonaBlocksVerify>
  );
}

autoOpen defaults to true. Set autoOpen={false} if you’d rather trigger open() yourself from a user gesture — recommended for the popup/wallet venue in browsers that are strict about popup blockers — and drive it with usePersonaBlocks directly instead of the component.

usePersonaBlocks()

The lower-level hook gives you open/close plus ready/error state, without any rendered markup:

import { useRef } from 'react';
import { usePersonaBlocks } from '@personablocks/react';

function InlineVerify({ clientToken }: { clientToken: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const { open, ready, error } = usePersonaBlocks({
    clientToken,
    flow: 'phone',
    container: containerRef.current,
    onComplete: ({ sessionId, vicId, method }) => {},
  });

  return (
    <div>
      <div ref={containerRef} />
      <button disabled={!ready} onClick={open}>
        Start verification
      </button>
      {error && <p role="alert">{error.message}</p>}
    </div>
  );
}

Note

ready becomes true once PersonaBlocks.create() has returned for the current options — it mirrors the SDK’s onReady timing and does not mean a venue is open. ready turning true is not itself a user gesture, so it can’t satisfy the popup venue’s gesture requirement on its own — wire open() to a real click for wallet flows.

Options

Both the component and the hook accept the SDK’s CreateOptions fields — clientToken, flow, appearance, hostOrigin, pollIntervalMs, onReady, onComplete, onCancel, onError, onEvent — plus:

• scriptOrigin — origin to load the hosted /sdk/v1.js from (forwarded to loadPersonaBlocks()).
• container (hook only — the component manages its own container <div>).
• autoOpen, className, style, children (component only).

What to read next

• SDK reference — the full option, callback, and error surface these bindings pass through.
• Theming — the appearance object used above.
• Venues — the popup gesture rule the autoOpen={false} guidance exists for.