> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React

> Install the React SDK and render the Vouchmark widget as a component.

`@vouchmark/widget-react` provides a drop-in React component with full TypeScript types. It manages script loading, lifecycle callbacks, and cleanup automatically.

## Installation

```bash theme={null}
npm install @vouchmark/widget-react
# or
pnpm add @vouchmark/widget-react
# or
yarn add @vouchmark/widget-react
```

## Quick start

```tsx theme={null}
import { VouchmarkWidget } from "@vouchmark/widget-react";

export function VerifyButton() {
  return (
    <VouchmarkWidget
      widgetId="wgt_your_widget_id"
      publicKey="live_pk_your_public_key"
      environment="live"
      applicant={{
        email: "applicant@example.com",
        businessName: "Acme Ltd",
        registrationNumber: "RC123456",
      }}
      onSuccess={(applicant) => {
        console.log("Approved:", applicant.id, applicant.riskScore);
      }}
      onAbandon={() => {
        console.log("User closed the widget");
      }}
      onError={(error) => {
        console.error("Widget error:", error.code, error.message);
      }}
    />
  );
}
```

The component renders a styled button by default. When clicked, it opens the widget overlay.

## Props

| Prop              | Type                                   | Required | Description                                                                                               |
| ----------------- | -------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `widgetId`        | `string`                               | Yes      | Widget ID from the dashboard. Must match the widget's `environment`.                                      |
| `publicKey`       | `string`                               | Yes      | Publishable key: `test_pk_…` (sandbox) or `live_pk_…` (live).                                             |
| `environment`     | `"sandbox" \| "live"`                  | Yes      | `"sandbox"` with `test_pk_…`, `"live"` with `live_pk_…`. See [Environments](/sdks/overview#environments). |
| `applicant`       | `ApplicantInput`                       | No       | Pre-fill applicant fields.                                                                                |
| `referenceId`     | `string`                               | No       | Your internal reference ID.                                                                               |
| `sessionToken`    | `string`                               | No       | Signed server token for secure mode.                                                                      |
| `locale`          | `string`                               | No       | Language code. Default `"en"`.                                                                            |
| `trigger`         | `ReactNode`                            | No       | Custom trigger element. Defaults to a styled button.                                                      |
| `autoOpen`        | `boolean`                              | No       | Open immediately on mount. Default `false`.                                                               |
| `onSuccess`       | `(applicant: ApplicantResult) => void` | No       | Fires on approval.                                                                                        |
| `onAbandon`       | `() => void`                           | No       | Fires when user closes early.                                                                             |
| `onError`         | `(error: WidgetError) => void`         | No       | Fires on unrecoverable error.                                                                             |
| `onStepCompleted` | `(step: StepResult) => void`           | No       | Fires after each module.                                                                                  |
| `onReady`         | `() => void`                           | No       | Fires when widget script is loaded.                                                                       |

## Custom trigger

Pass any React element as the `trigger` prop to replace the default button:

```tsx theme={null}
<VouchmarkWidget
  widgetId="wgt_..."
  publicKey="live_pk_..."
  environment="live"
  trigger={<button className="btn-primary">Start KYB</button>}
  onSuccess={(applicant) => { /* ... */ }}
/>
```

## Imperative control with `useVouchmark`

For programmatic open/close without rendering a trigger:

```tsx theme={null}
import { useVouchmark } from "@vouchmark/widget-react";

export function CustomFlow() {
  const { open, close, isReady } = useVouchmark({
    widgetId: "wgt_...",
    publicKey: "live_pk_...",
    environment: "live",
    onSuccess: (applicant) => { /* ... */ },
  });

  return (
    <button onClick={open} disabled={!isReady}>
      Begin verification
    </button>
  );
}
```

## TypeScript types

```ts theme={null}
interface ApplicantInput {
  email?: string;
  businessName?: string;
  registrationNumber?: string;
  phone?: string;
  tin?: string;
  jurisdiction?: string;
  industry?: string;
}

interface ApplicantResult {
  id: string;
  status: "approved" | "rejected" | "requires_review";
  riskScore: number | null;
  decisionReason: string | null;
  subject: ApplicantInput;
}

interface WidgetError {
  code: string;
  message: string;
}

interface StepResult {
  moduleId: string;
  status: "passed" | "failed" | "requires_review";
}
```

## Next.js App Router

The widget component is a client component. Use it inside a `"use client"` boundary:

```tsx theme={null}
"use client";

import { VouchmarkWidget } from "@vouchmark/widget-react";

export function KybWidget() {
  return (
    <VouchmarkWidget
      widgetId={process.env.NEXT_PUBLIC_VOUCHMARK_WIDGET_ID!}
      publicKey={process.env.NEXT_PUBLIC_VOUCHMARK_PUBLIC_KEY!}
      environment="live"
      onSuccess={(applicant) => { /* redirect or update state */ }}
    />
  );
}
```

## Server-side session creation

For signed sessions, create the token on the server and pass it as a prop:

```tsx theme={null}
// app/api/kyb-session/route.ts
import { Vouchmark } from "@vouchmark/node";

const vouchmark = new Vouchmark({ secretKey: process.env.VOUCHMARK_SECRET_KEY! });

export async function POST(req: Request) {
  const { email } = await req.json();
  const session = await vouchmark.sessions.create({
    widgetId: "wgt_...",
    environment: "live",
    applicant: { email },
  });
  return Response.json({ token: session.token });
}
```