Forms
JavaScript SDK v1.4.0 — Forms
Renders a published Optima Edge web form (GET /edge/v1/forms/:id) into your own page — the hosted page (GET /edge/v1/pages/:token/:slug) is X-Frame-Options: DENY, so embedding a form in your own markup has to be SDK-side. Like the display engine, this is a lazy chunk — dist/forms.js, ≤ 10 KB gzip, loaded on first use of forms.render/forms.load, resolved the same way (next to optima.js itself; see Content).
optima.forms.render("signup", "#signup-host", {
onSuccess: ({ dropped, double_opt_in }) => console.log("submitted", { dropped, double_opt_in }),
onError: (e) => console.warn("form unavailable", e.kind),
theme: { "--optima-form-accent": "#0ea5e9" },
});target is a CSS selector or an Element. The rendered markup is deliberately unstyled beyond class hooks:
<form class="optima-form" novalidate>
<label class="optima-form__field optima-form__field--email">
<span class="optima-form__label">Email</span>
<input type="email" name="email" required aria-required="true">
</label>
<!-- one .optima-form__field per declared field, input types mapping 1:1
to the closed vocabulary (text/email/number/textarea/checkbox/select/
hidden; "phone" -> type="tel"); a consent-kind field always renders
as a checkbox regardless of its declared input_type -->
<div class="optima-form__hp" style="position:absolute;left:-9999px;…">
<input name="_hp" autocomplete="off" tabindex="-1" aria-hidden="true">
</div>
<div class="optima-form__message" role="alert"></div>
<button type="submit" class="optima-form__submit">Submit</button>
</form>Style it with your own CSS against those class names; --optima-form-gap (spacing) and --optima-form-accent (the submit button's accent colour) are the two theme hooks theme sets directly on the form root as CSS custom properties.
Bot rejection: the hidden _hp field (never focusable, autocomplete="off") and the submit button — disabled until min_submit_interval_sec has elapsed since render — are both part of the same uniform-403 contract the gateway enforces: a filled honeypot, a too-fast submit, or a bad/expired nonce all come back indistinguishable. The SDK's response to a 403 is to destroy the current form and render a fresh one in place (a new fetch mints a new nonce and restarts the interval clock) with a generic "Please try again." message — never a hint at which check failed.
Submit outcomes, each shown in the .optima-form__message region: 202 shows success_message (or redirects to success_redirect_url if the form isn't double_opt_in and one is configured), with double_opt_in: true shown as a "check your inbox to confirm" note instead of redirecting; 400 shows the server's own message inline (it names the field); 409 (already submitted) is treated exactly like success. Every successful submission emits form:submitted with {id, dropped, double_opt_in} — dropped lists any submitted key the server didn't admit (not_asked: elided by progressive profiling or max_fields on this render; not_in_form: not a real field at all). Required fields are checked before anything is sent: an empty one is marked aria-invalid with a "Required" message and focused. An unticked optional consent box sends nothing (it never withdraws a consent given elsewhere), and an unanswered optional select is omitted. After a successful submission that does not redirect, the form stays disabled; call forms.render again to collect another response.
Headless
const result = await optima.forms.load("signup", { lang: "fr" });
if ("definition" in result) {
const { definition, submit } = result;
// build your own UI from definition.fields, then:
const outcome = await submit({ email: "visitor@example.com" });
}submit(values) applies the exact same honeypot/nonce/interval contract as the built-in renderer — you supply the coerced values (a checkbox/consent field as a boolean, a number field as a number, everything else as a string), the SDK adds nonce and defaults _hp to "" if you don't set one.
Linking to the hosted page
optima.forms.pageUrl(url) appends ?device_id= to a GET /edge/v1/pages/:token/:slug link — needed when that page is served from a different registrable domain than your site, since a navigation can't carry the _optima_did cookie across that boundary. Synchronous, and never loads the forms chunk (it's pure URL munging off the device id the SDK already holds):
const href = optima.forms.pageUrl("https://forms.example.com/p/tok123/signup");
// -> "https://forms.example.com/p/tok123/signup?device_id=<the visitor's device id>"