Forms reference — Balancee Astro
Balancee for Astro has two forms: the contact form (“Tell us about your project.”) on the Contact page and the Services page
(src/components/sections/ContactForm.astro, <Form name="contact">), and the newsletter box in the footer of every page
(NewsletterForm.astro, form newsletter). Each works in one of three ways, chosen with environment variables (copy
.env.example to .env, or set them in your host’s dashboard); no code changes.
| Form | Where | form in the payload |
Fields (name → label) |
Required |
|---|---|---|---|---|
| Contact | Contact, Services | contact |
Name Name, Company Company, Email Email, Phone Phone, Service I’m interested in …, Message Tell us about your project. |
Name, Company, Email |
| Newsletter | every page (footer) | newsletter |
Email Email |
Email |
“I’m interested in …” is a group of radio buttons, one per service (contactForm in src/content/pages/shared.json): the
visitor picks one or none. The e-mail must look like an e-mail address.
| Mode | Set | Hosting | Where submissions go |
|---|---|---|---|
| Demo (default) | nothing | any static host | Nowhere: the form shows “Thank you” and logs the fields in the browser console. |
| Static | PUBLIC_FORM_ENDPOINT |
any static host | Posted from the browser to a form service or webhook. |
| Server | PUBLIC_FORM_MODE=server + FORM_PROVIDER |
a host with an Astro adapter | Delivered by the site’s own route to console, webhook, Mailchimp or Resend. |
Every mode shows the same states on the Submit button (spinner, “Thank you”, “Something went wrong”), keeps the typed values
after an error, resets the form after success and drops spam caught by the hidden honeypot field (fax). The PUBLIC_
variables are read when the site is built: rebuild (or restart npm run dev) after changing them.
<Form> / <NewsletterForm> → browser: PUBLIC_FORM_ENDPOINT, or the demo → server mode: POST /api/forms/<form> → deliver() → provider(s) chosen in FORM_PROVIDERformEndpoint("contact") in src/lib/forms/endpoint.ts decides where a form posts: /api/forms/<form> in server mode, else
PUBLIC_FORM_ENDPOINT, else nothing (demo mode). The browser parts are src/design-system/scripts/form.ts and newsletter.ts.
1. Before sending: the check
Section titled “1. Before sending: the check”The contact form checks the fields when Submit is pressed: an empty required field or an e-mail that isn’t one gets the focus, is marked invalid and shows its message until it is changed. The newsletter box uses the browser’s own check. Without JavaScript the browser’s check runs and the form posts to the endpoint as an ordinary form.
2. Static mode: form services and webhooks
Section titled “2. Static mode: form services and webhooks”Set PUBLIC_FORM_ENDPOINT to the URL the service gives you. The forms post multipart/form-data with Accept: application/json;
the service must answer with a 2xx status, anything else shows “Something went wrong” (“Try again” in the newsletter box).
| Service | PUBLIC_FORM_ENDPOINT |
Notes |
|---|---|---|
| Formspree | https://formspree.io/f/<form id> |
Emails you each submission. |
| Web3Forms | https://api.web3forms.com/submit |
Also set PUBLIC_FORM_ACCESS_KEY (sent as the hidden field access_key). |
| Getform, Basin | the form’s endpoint URL | |
| Zapier, Make, n8n, Pipedream | the webhook (“catch hook”) URL | Route submissions anywhere: Mailchimp, Google Sheets, Slack, a CRM. |
Fields sent: every field by its name plus form (contact or newsletter) and subject. The style guide’s sample form never
sends (it is marked demo).
3. Server mode: your own route
Section titled “3. Server mode: your own route”- Add the adapter for your host:
npx astro add vercel(ornetlify,node, …). - Set
PUBLIC_FORM_MODE=serverand choose providers withFORM_PROVIDER.
The forms then post to POST /api/forms/<form> (src/lib/forms/route.ts, added by src/integrations/forms.ts; every other page
stays prerendered). Without an adapter the build stops with NoAdapterInstalled. Astro rejects cross-site posts to the route.
The route answers JSON: 200 { "status": "success" }, or 500 { "status": "error" } (404 unknown form, 400 not form data).
FORM_PROVIDER |
What happens | Variables |
|---|---|---|
console (default) |
Printed to the server log. For development. | — |
webhook |
Posted as JSON to a URL — Zapier, Make, n8n, Pipedream, Formspree, your own API. | FORM_WEBHOOK_URL, optional FORM_WEBHOOK_SECRET (sent as Authorization: Bearer …) |
mailchimp |
Sender added or updated in an audience, tagged with the form, the rest saved as a note. | MAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID, optional MAILCHIMP_STATUS |
resend |
Emailed to you; replying answers the sender. | RESEND_API_KEY, FORM_EMAIL_TO, FORM_EMAIL_FROM |
Use several with a comma (FORM_PROVIDER=resend,mailchimp). If one fails the visitor sees the error state and the reason is
logged on the server. A provider that needs a variable and doesn’t find it stops the submission with Missing environment variable <NAME> (see .env.example). Add your own provider in src/lib/forms/providers/index.ts.