@trustsig/react

React Context Provider and hooks for TrustSig bot protection. React 18 or 19.

Installation

npm install @trustsig/react

Usage

1. Setup Provider

Wrap your application or specific routes with the provider.

"use client";
import { TrustSigProvider } from '@trustsig/react';

export default function RootLayout({ children }) {
  return (
    <TrustSigProvider siteKey="pk_live_..." autoScan>
      {children}
    </TrustSigProvider>
  );
}

2. Using the Hook

Use useTrustSig to access the analysis methods.

"use client";
import { useTrustSig } from '@trustsig/react';

export function ActionForm() {
  const { getResponse, isLoaded, error } = useTrustSig();

  const handleSubmit = async (e) => {
    e.preventDefault();
    const response = await getResponse(); // { request_id, token } | null

    if (response?.token) {
      await fetch('/api/secure-action', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-TrustSig-Response': response.token,
        },
        body: JSON.stringify({ data: '...' }),
      });
    }
  };

  return (
    <button onClick={handleSubmit} disabled={!isLoaded}>
      Submit Secure Action
    </button>
  );
}

getResponse() resolves to { request_id, token } or null (script failed to load, timed out, or no verdict yet — inspect error). The server is the trust boundary: always verify the token with @trustsig/server.

API

| Export | Type | Description | | --- | --- | --- | | isLoaded | boolean | True once the TrustSig script has loaded. | | error | Error \| null | Set if script loading failed or timed out (SCRIPT_LOAD_FAIL / SCRIPT_LOAD_TIMEOUT). | | getResponse() | Promise<TrustSigResponse \| null> | Current analysis result. | | scan() | Promise<TrustSigResponse \| null> | Manually trigger a new analysis scan. | | setCustomData(data) | void | Update custom metadata for subsequent scans. |

Provider props

siteKey (required), scriptUrl, interceptRequests, autoScan, debug, nonce, env, customData. Changing customData updates the running script in place — it does not re-inject the script or reset state.