React SDK reference

@revokegpt/react is a thin React wrapper over @revokegpt/js: a RevokeGPT component and a useRevokeGPT hook. The entry carries "use client", so it works in the Next.js App Router, and it touches no window during a server render. Peer dependency: React ^18.2 || ^19. For a walkthrough, see the React quickstart.

Install

Not published yet

@revokegpt/react is not on its registry yet, so install it from a checkout of the repository as in the quickstart. After the first release the registry command applies.

npm install @revokegpt/react @revokegpt/js     # after the first release

Exports

RevokeGPT, useRevokeGPT, and the types RevokeGPTHandle, RevokeGPTProps, UseRevokeGPTOptions, UseRevokeGPTResult, Badge, Locale, Size, Theme.

Options

RevokeGPT props

Prop	Type	Default	Meaning
sitekey	string	required	Your site key (rgpk_...).
theme	'light' | 'dark' | 'auto'	none	Widget theme.
size	'normal' | 'compact' | 'invisible'	invisible	Widget size.
hl	Locale	none	Widget language.
action	string	none	The action the token is issued for.
cdata	string	none	Optional string passed with the widget.
tabIndex	number	none	The widget frame’s tab order (not the host div’s).
badge	'bottomright' | 'bottomleft' | 'inline'	bottomright	Invisible size only.
origin	string	https://js.revokegpt.com	Widget origin, a bare https: origin, validated by @revokegpt/js.
nonce	string	none	CSP nonce for the injected script.
onVerify	(token: string) => void	none	Receives the response token.
onExpire	() => void	none	The token expired.
onError	(code: string) => void	none	Receives the error code.
className, id, style, data-*, aria-*	host <div> props	none	Passed through to the host <div>. children is dropped.

Changing sitekey, size, theme, hl, action, cdata, tabIndex, badge, origin or nonce destroys the widget and renders a new one. Callbacks are read through a ref, so a new onVerify on each render never recreates it.

useRevokeGPT options

Option	Type	Default	Meaning
sitekey	string	required	Your site key.
action	string	none	The default action. execute(action) overrides it per call.
cdata	string	none	Optional string passed with the widget.
hl	Locale	none	Widget language.
theme	Theme	none	Widget theme.
badge	Badge	bottomright	Badge position.
origin	string	https://js.revokegpt.com	Widget origin.
nonce	string	none	CSP nonce.

The hook’s widget is always invisible. Changing any option except action recreates the widget; action is read when a request starts.

Methods

RevokeGPT handle

const ref = useRef<RevokeGPTHandle>(null);
<RevokeGPT ref={ref} sitekey="rgpk_..." size="normal" onVerify={(token) => send(token)} />;
const token = await ref.current?.execute();

interface RevokeGPTHandle {
  execute(): Promise<string>;
  reset(): void;
  getResponse(): string;
}

• execute() runs the challenge and resolves with the token. It rejects with Error('widget is not ready') before the widget exists.
• reset() resets the widget.
• getResponse() returns the live token, or ''.

useRevokeGPT

function useRevokeGPT(opts: UseRevokeGPTOptions): { execute(action?: string): Promise<string>; ready: boolean }

An invisible widget with no markup of your own. execute(action?) waits for the widget, runs the challenge and resolves with the token. Calls run one at a time, so two calls with different actions both resolve. It rejects after unmount or with Error('widget is not ready'). ready is true once the script is loaded and the widget exists.

const { execute, ready } = useRevokeGPT({ sitekey: 'rgpk_...', action: 'login' });
const token = await execute('checkout'); // the action argument is optional

Errors and failure model

• A script that fails to load, or a bad origin, calls onError('load-error').
• A render failure calls onError('render-error').
• Other codes come from the widget (for example network-error). See errors.
• useRevokeGPT().execute rejects when the script fails to load, after unmount, or if the widget is not ready.

Configuration

No environment variables. Allow the widget origin in script-src and frame-src, or pass nonce; see session tokens and cookies. In StrictMode, mount, unmount, mount leaves exactly one widget.

Security notes

• The token is only a claim until your server verifies it (Node.js, Python, PHP or siteverify).
• There is no script-URL prop. origin takes a bare https: origin and is validated by @revokegpt/js.