Next.js

Submit from a Next.js App Router client component, or through a server action with a secret key.

There are two good ways to submit from Next.js. Post from the browser in a client component, which keeps each visitor's own IP for rate limits and works with every spam check. Or post from a server action, which keeps the form working without JavaScript.

Item	Client component	Server action
Works without JavaScript	No	Yes
Rate limits count	Each visitor	Your server's IP
Ikiform human check	Use `challenge` from the SDK	Skipped with a secret key
Allowed domains	Checked against the browser's origin	Skipped with a secret key
Needs a secret key	No	Yes

Install the SDK

Terminal

npm install @ikiform/sdk

The SDK is optional. Everything below also works with fetch; see JavaScript and fetch.

From a client component

app/contact/contact-form.tsx

"use client";

import { submit } from "@ikiform/sdk";
import { useState } from "react";

type Status = "idle" | "sending" | "sent" | "error";

export function ContactForm() {
  const [status, setStatus] = useState<Status>("idle");
  const [errors, setErrors] = useState<Record<string, string[]>>({});
  const [message, setMessage] = useState("");

  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setStatus("sending");
    const result = await submit("frm_xxxxxxxxxxxxxxxx", new FormData(event.currentTarget));
    if (result.ok) return setStatus("sent");
    setErrors(result.error.fields ?? {});
    setMessage(result.error.message);
    setStatus("error");
  }

  if (status === "sent") return <p>Thanks, we got it.</p>;

  return (
    <form onSubmit={onSubmit} noValidate>
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" required aria-invalid={Boolean(errors.email)} />
      {errors.email ? <p>{errors.email[0]}</p> : null}
      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" />
      <input name="_gotcha" type="text" tabIndex={-1} autoComplete="off" hidden />
      {status === "error" && !Object.keys(errors).length ? <p role="alert">{message}</p> : null}
      <button disabled={status === "sending"}>{status === "sending" ? "Sending" : "Send"}</button>
    </form>
  );
}

submit never throws. It resolves to { ok: true, id } or { ok: false, error, status, requestId }.
error.fields maps field ids to messages when the form has fields defined.
Render the component from any server component page, for example app/contact/page.tsx.

With the Ikiform human check

If the form's spam check is Ikiform, get a token right before each submit. challenge mounts a small ikiform.com frame that stays invisible unless Turnstile needs a click.

contact-form.tsx

const data = new FormData(event.currentTarget);
const turnstileToken = await challenge("frm_xxxxxxxxxxxxxxxx");
const result = await submit("frm_xxxxxxxxxxxxxxxx", data, { turnstileToken });

Import it with import { challenge, submit } from "@ikiform/sdk";. Tokens are single use, so call it once per submit.

From a server action

Create a secret key in the dashboard under API keys with the submissions:write scope, and store it as an environment variable. Never expose it to the browser: don't prefix it with NEXT_PUBLIC_.

.env.local

IKIFORM_SECRET_KEY=ik_sk_your_secret_key

app/contact/actions.ts

"use server";

export interface ContactState {
  ok: boolean;
  message: string;
  fields?: Record<string, string[]>;
}

export async function sendContact(_previous: ContactState, formData: FormData): Promise<ContactState> {
  const body = new URLSearchParams();
  for (const [name, value] of formData) {
    if (typeof value === "string" && !name.startsWith("$ACTION")) body.append(name, value);
  }
  const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
    method: "POST",
    headers: {
      Accept: "application/json",
      Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`,
    },
    body,
  });
  const result = await response.json();
  if (result.ok) return { ok: true, message: "Thanks, we got it." };
  return { ok: false, message: result.error.message, fields: result.error.fields };
}

app/contact/contact-form.tsx

"use client";

import { useActionState } from "react";
import { type ContactState, sendContact } from "./actions";

const initial: ContactState = { ok: false, message: "" };

export function ContactForm() {
  const [state, action, pending] = useActionState(sendContact, initial);

  if (state.ok) return <p>{state.message}</p>;

  return (
    <form action={action}>
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" required />
      {state.fields?.email ? <p>{state.fields.email[0]}</p> : null}
      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" />
      {state.message && !state.fields ? <p role="alert">{state.message}</p> : null}
      <button disabled={pending}>{pending ? "Sending" : "Send"}</button>
    </form>
  );
}

Posts sent from your server all come from your server's IP address, so Ikiform's per-visitor rate limits count every visitor together. The Standard preset allows 5 posts a minute per IP and form, which a busy site can hit. Post from the browser when you can, or choose the Relaxed or Custom rate limit for forms you proxy through a server.

The SDK's submit can be used in a server action too, but it doesn't send an Authorization header, so a form with allowed domains or the Ikiform human check would reject or flag the post. Use fetch with the secret key as shown.

Receive webhooks in a route handler

To act on each submission in your Next.js app, add a route handler. See Receiving webhooks.