NextJS & React
Build an accessible contact form with safe submission handling, Next.js navigation boundaries, and explicit configuration approval.
Integrate with your AI agent
A prompt tailored to this guide, with the relevant Basestack skills.
Preview prompt
Paste this into your coding agent. It will inspect your app and ask for any missing configuration. Keep private tokens out of the conversation.
Basestack Forms uses ordinary HTML/HTTP; there is no Forms React SDK to install. Reuse your application's form and styling patterns. The example below matches the reviewed React/Next.js reference.
Before you start
- Copy the real submission endpoint from your form's dashboard Setup tab.
- Confirm exact field names, saved validation rules, the configured honeypot, enabled state, and notification/webhook destinations.
- Choose an interactive JSON response (
?mode=rest) or native HTML redirects.Acceptalone does not select JSON response mode. - Keep private API/MCP tokens out of the browser. The submission endpoint is public, not an account credential.
Contact form
The synchronous ref lock prevents repeated submit events before pending state
rerenders. FormData is captured before controls are disabled. The example
checks both HTTP status and success: true, preserves inputs on failure, and
announces status outside the form's aria-busy subtree.
"use client";
import { useId, useRef, useState, type FormEvent } from "react";
export function ContactForm({ endpoint }: { endpoint: string }) {
const id = useId();
const inFlight = useRef(false);
const [pending, setPending] = useState(false);
const [status, setStatus] = useState("");
const [error, setError] = useState("");
async function submit(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
if (inFlight.current) return;
inFlight.current = true;
const form = event.currentTarget;
setStatus("");
setError("");
try {
const fields = new FormData(form);
setPending(true);
setStatus("Sending your messageā¦");
const url = new URL(endpoint);
url.searchParams.set("mode", "rest");
const response = await fetch(url, {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: fields.get("name"),
email: fields.get("email"),
message: fields.get("message"),
}),
});
const body: unknown = await response.json();
if (
!response.ok ||
typeof body !== "object" ||
body === null ||
!("success" in body) ||
body.success !== true
) {
throw new Error("Submission was not accepted.");
}
setStatus("Your message was accepted.");
form.reset();
} catch {
setStatus("");
setError(
"We could not confirm submission. Your input is still here. Check before retrying.",
);
} finally {
inFlight.current = false;
setPending(false);
}
}
return (
<>
<form
onSubmit={submit}
aria-busy={pending}
aria-describedby={error ? `${id}-error` : undefined}
>
<fieldset disabled={pending}>
<legend>Contact us</legend>
<label htmlFor={`${id}-name`}>Name</label>
<input id={`${id}-name`} name="name" required autoComplete="name" />
<label htmlFor={`${id}-email`}>Email</label>
<input
id={`${id}-email`}
name="email"
type="email"
required
autoComplete="email"
/>
<label htmlFor={`${id}-message`}>Message</label>
<textarea id={`${id}-message`} name="message" required />
<button type="submit">{pending ? "Sendingā¦" : "Send message"}</button>
</fieldset>
</form>
<p role="status" aria-atomic="true">
{status}
</p>
{error ? (
<p id={`${id}-error`} role="alert">
{error}
</p>
) : null}
</>
);
}Pass your real dashboard endpoint as endpoint. The example sends only name,
email, and message. If a honeypot is configured, add its exact empty named
input and include it in the JSON payload; do not assume a magic field name.
Its name must not collide with an ordinary field.
The lock prevents local duplicate events, not multiple tabs or server retries. Do not automatically retry an ambiguous failure. Accepted does not mean email or webhook delivery was verified.
Next.js configuration and navigation
A static public endpoint needs no new Suspense boundary just because it is used by a form. For genuinely request-time configuration, place the async work beneath the appropriate page/segment boundary and check client navigation, not only a direct load. A shared layout boundary is not proof that the page is covered.
The following example deliberately reads configuration at request time using
connection() (Next.js 15+). It is unnecessary for build-time public configuration
and must not be copied unchanged into static export. Adapt to your installed
router/rendering settings rather than upgrading or changing prefetching options.
import { Suspense } from "react";
import { connection } from "next/server";
import { ContactForm } from "../../components/contact-form";
async function ConfiguredContactForm() {
await connection();
const endpoint = process.env.BASESTACK_FORMS_ENDPOINT;
if (!endpoint)
return <p role="alert">Contact form is temporarily unavailable.</p>;
return <ContactForm endpoint={endpoint} />;
}
export default function ContactPage() {
return (
<main>
<h1>Contact us</h1>
<p>You can contact our team using the form below.</p>
<Suspense fallback={<p role="status">Loading contact formā¦</p>}>
<ConfiguredContactForm />
</Suspense>
</main>
);
}Set BASESTACK_FORMS_ENDPOINT to the actual dashboard URL. It remains
browser-visible when passed to the client; never substitute a management token.
Keep ordinary page content outside the configuration boundary. Suspense streams
a fallback but does not remove request latency. Follow the installed framework's
layout/Suspense rules.
Rules and management approval
For this contact example, propose required name, required email with email
format, and required message. Read the current rules first, preserve existing
fields/constraints, and show the merged replacement/diff for approval. Rules use
strict ordinary-field matching; exclude the configured honeypot from those rules
because the parser removes it before validation. See the
approval-gated template.
If MCP is available, discover tool schemas and permissions before promising changes. Rules may be writable while notification recipients require a dashboard sign-in and an appropriate role. A rules replacement is not a patch: reread before applying approved changes to avoid overwriting newer work. Reading these examples does not authorize changing accounts or sending submissions.
Attaching files
Keep the same lock, pending state, input preservation, and response checks.
Capture new FormData(form) before disabling controls, send it as the body, and
remove the JSON Content-Type header; keep Accept: application/json and
mode=rest. Let the browser set the multipart boundary.
Enable both retention and file uploads in General settings first. Current limits are 1 MiB (1,048,576 bytes) per file and five files total per submission, across all inputs. Add named file inputs and validate size/count for feedback, while retaining authoritative server checks. File fields are excluded from email/webhook data; acceptance does not prove storage or downstream delivery. See File uploads and the HTTP contract.
Verify in the running application
Use mocks for accepted/rejected responses, malformed JSON, network failures, same-tick duplicate submits, retained input, pending states, and success reset. Inspect labels, keyboard focus, and live announcements. Do not trigger a real submission or notification without permission.
Run development mode: test a direct contact-page load and client-side navigation from another route, including development-only Instant validation where supported. Then run the production build. A build alone does not verify development routing.
Inspect the rendered form at desktop/mobile sizes with the app's actual CSS pipeline, including CSS Module mappings and pending/error states. Preserve framework/build configuration and existing CSS loaders; make only narrow, demonstrated compatibility fixes. Record blocked visual or navigation checks rather than reporting them as passed.