React SDK

React components and hooks for advanced verification flows with full control over the UI.

Looking for the simplest integration?

Most projects should use the Widget SDK — it's a web component that works in React (and every other framework) with zero configuration. The React SDK is for advanced use cases where you need full control over the verification UI, such as custom-designed flows or deep integration with your React state management.

The React SDK requires you to create verification sessions on your server and pass the clientSecret to the frontend. This gives you full control over session lifecycle but requires more setup than the widget.

Installation

npm install @stile/react

StileProvider

Wrap the part of your app that needs verification access with <StileProvider>. It stores the clientSecret in context so child components can access the session.

import { StileProvider } from "@stile/react";

// clientSecret comes from your backend (created via POST /v1/verification_sessions)
<StileProvider clientSecret={clientSecret}>
  {/* Your verification UI lives here */}
</StileProvider>

Parameter	Type	Description
`clientSecret`required	`string`	The client_secret returned when you create a verification session on your server.
`children`required	`ReactNode`	Child components that need access to the verification session.

VerificationFlow

The main component. It renders a QR code for the user to scan with their wallet app, polls for status updates, and calls your callbacks when the session reaches a terminal state.

import { StileProvider, VerificationFlow } from "@stile/react";

export function VerifyPage({ sessionId, clientSecret }: Props) {
  return (
    <StileProvider clientSecret={clientSecret}>
      <VerificationFlow
        sessionId={sessionId}
        onComplete={(session) => {
          // Redirect or update your UI
          window.location.href = "/dashboard";
        }}
        onError={(error) => {
          console.error("Verification failed:", error.message);
        }}
        onCancel={() => {
          window.location.href = "/";
        }}
        appearance={{
          theme: "light",
          variables: {
            primaryColor: "#6366f1",
            borderRadius: "12px",
          },
        }}
      />
    </StileProvider>
  );
}

Parameter	Type	Description
`sessionId`required	`string`	The verification session ID (vks_...) to display.
`alreadyVerified`	`boolean`= false	If true, skips the QR flow and calls onComplete immediately.
`onComplete`	`(session: VerificationSession) => void`	Called when the session reaches the verified status.
`onError`	`(error: Error) => void`	Called when the session reaches the failed status.
`onCancel`	`() => void`	Called when the user cancels or the session is cancelled.
`appearance.theme`	`"light" \| "dark"`= "light"	Color scheme for the verification UI.
`appearance.variables`	`Record<string, string>`	CSS variable overrides. Supports primaryColor, borderRadius, and fontFamily.

useVerification hook

For custom UIs, use the useVerification hook directly. It polls the session status and gives you full control over rendering.

import { useVerification } from "@stile/react";

function CustomVerificationUI({ sessionId }: { sessionId: string }) {
  const { session, loading, error, cancel } = useVerification({
    sessionId,
    pollInterval: 2000,
    onComplete: (s) => console.log("Done!", s.id),
    onError: (e) => console.error("Failed:", e),
    onCancel: () => console.log("Cancelled"),
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!session) return null;

  return (
    <div>
      <p>Status: {session.status}</p>
      <button onClick={cancel}>Cancel</button>
    </div>
  );
}

Parameter	Type	Description
`sessionId`required	`string`	The session to track.
`pollInterval`	`number`= 2000	How often to poll for status updates (milliseconds).
`onComplete`	`(session: VerificationSession) => void`	Called when verified.
`onError`	`(error: Error) => void`	Called when failed.
`onCancel`	`() => void`	Called when cancelled.

Return value

Parameter	Type	Description
`session`	`VerificationSession \| null`	The current session object. null while loading.
`loading`	`boolean`	True on the initial fetch.
`error`	`Error \| null`	Set if the fetch fails.
`refresh`	`() => Promise<void>`	Manually re-fetch the session status.
`cancel`	`() => Promise<void>`	Cancel the session.

Installation

StileProvider

VerificationFlow

useVerification hook

Return value

On this page