Embed widget
The Formspring embed widget is a single JavaScript file you drop on any page. It renders a form, handles submission, manages success and error states, and ships to your inbox — without you writing any HTML, validation, or fetch logic.
For static sites, marketing pages, and most "I just need a contact form" cases, the embed beats a hand-rolled <form> every time.
When to use the embed
| Use case | Embed | Raw POST |
|---|---|---|
| Static site / marketing landing page | Yes | Possible but more code |
| You want spam protection without JS work | Yes | Captcha you wire yourself |
| You need full control over markup | No | Yes |
| Your site is a SPA with strict CSP | Headless mode | Yes |
| You're posting from a mobile app | No | Yes (or use the API) |
| You want a form that auto-updates when you change fields in the dashboard | Yes | No (you'd update HTML manually) |
The embed reads its field configuration from the form on the dashboard. Add a field in the editor and it appears on every page using the embed — no deploy needed.
For raw HTML POST, see the Forms quickstart. For programmatic submission, see the REST API.
What the embed does
- Reads the form configuration from the dashboard (fields, labels, validation rules).
- Renders an HTML form with sensible defaults that match your form's branding settings.
- Handles client-side validation, character counters, file uploads, and country-aware phone fields.
- Injects the configured honeypot, hCaptcha, or reCAPTCHA challenge.
- Submits to
https://formspring.io/f/{form-id}with the right headers. - Renders success or error UI based on the form's settings.
- Calls any callbacks you registered (
onSuccess,onError, etc.).
Browser compatibility
The widget is built for modern browsers:
- Chrome, Edge, Firefox, Safari — last 2 major versions
- iOS Safari 15+, Android Chrome — last 2 major versions
- No IE11 support
Underlying tech: vanilla JS (no framework runtime), CSS custom properties for theming, the modern Fetch API. Works without any bundler on your side. The widget weighs roughly 18KB minified and gzipped.
Plan availability
- Free, Starter, Pro, Pro+ — full embed support, all features.
- Free plan shows a tiny "Powered by Formspring" footer in the widget. All paid plans hide it.
There are no per-embed-load fees. The widget hits a CDN, the form configuration is cached for 5 minutes, and submissions count against your normal monthly quota.
Data residency
The widget is served from the same domain as your dashboard (formspring.io). Form submissions also land on formspring.io. If you have strict CSP or data-residency requirements, see Install → for the CSP entries you'll need and Customization → for headless mode (where you handle the network call yourself).
Two modes
UI mode (default): the widget renders its own form HTML. You write <div id="my-form"></div> and the widget fills it in.
Headless mode: the widget exposes only the validation, file-upload, and submission logic. You provide your own HTML. Useful when your design system is non-negotiable. Covered in Customization →.
How submissions are tracked
Every submission via the embed includes a source: "embed" flag in the database. You can filter for embed-originated submissions in the dashboard or via the API, which is useful for separating widget traffic from raw POST traffic when you're debugging.
The widget also sets a source_url field with the page URL where the form was submitted. If you have the same form embedded across many pages, that field tells you which page the submission came from without you having to set up separate forms.
Updating without re-deploying
The form configuration (fields, labels, validation rules) is read from the dashboard at render time and cached at the CDN edge for 5 minutes. Add a new field on the dashboard and within 5 minutes every embed instance picks it up — no deploy, no cache-bust, no version bump.
If you need a faster propagation for a critical change (e.g. a typo in a label), the form's edit page has a Purge embed cache button that drops the edge cache immediately.