Next.js - Raykoi

npm install @raykoi/sdk

Same useRaykoiForm hook as React — this page covers Next.js-specific placement and an optional server-side pattern.

App Router

useRaykoiForm is a hook, so the component that calls it needs 'use client' — same rule as any other stateful hook, not something Raykoi adds on top. Keep that component in its own file and import it into your (unchanged) Server Component page:

// app/contact/contact-form.tsx
'use client';
import { useRaykoiForm, RaykoiFieldError, RaykoiStatus } from '@raykoi/sdk/react';

export function ContactForm() {
  const { submit, submitting } = useRaykoiForm('YOUR_PUBLIC_ID');

  return (
    <form onSubmit={submit}>
      <input type="email" name="email" required />
      <RaykoiFieldError name="email" />
      <button type="submit" disabled={submitting}>
        {submitting ? 'Sending…' : 'Submit'}
      </button>
      <RaykoiStatus />
    </form>
  );
}

// app/contact/page.tsx — a Server Component, no changes needed here
import { ContactForm } from './contact-form';

export default function ContactPage() {
  return <ContactForm />;
}

Beyond that one standard React Server Components boundary, there’s nothing Raykoi-specific to configure — no provider, no root-layout wrapper, no next.config.js changes.

Pages Router

Every component renders client-side by default (no Server/Client Component split), so useRaykoiForm works with zero setup — identical usage to plain React.

Submitting from a Server Action

A Server Action runs on your server, so it can authenticate with a secret API key and skip the CAPTCHA gate entirely — the same pattern as Node.js, using the canonical form-scoped client:

// app/contact/actions.ts
'use server';
import { createClient } from '@raykoi/sdk';

const client = createClient({ apiKey: process.env.RAYKOI_SECRET_KEY });
const form = client.form('YOUR_PUBLIC_ID');

export async function submitContactForm(data: { email: string; message: string }) {
  await form.submit(data);
}

This bypasses the point of a client-submitted form — CAPTCHA, quota checks tied to the visitor’s own identity, and network-failure retries all assume the browser is the one calling submit(). Reach for a Server Action only when you deliberately want server-authenticated submission (e.g. gating behind your own app’s auth), not as the default Next.js pattern — useRaykoiForm above is that default.

Using Remix or another React meta-framework instead? See Meta-Frameworks.

​App Router

​Pages Router

​Submitting from a Server Action

App Router

Pages Router

Submitting from a Server Action