Forms — Balancee Astro
The two forms of this Astro template work as soon as you run it: the contact form (“Tell us about your project.”, on Contact and Services) and the newsletter box in the footer of every page.
The contact form checks the three required fields (Name, Company and Email) and shows “Please fill out this field.” or
“Please enter a valid email address.” under a field that is missing or wrong, shows a spinner on its Submit button while
sending, says “Thank you” and clears the fields, keeps what the visitor typed when something fails (“Something went
wrong”), and drops spam with a hidden honeypot field. The newsletter box takes an e-mail address, says “Thank you” and
shows “Try again” when sending fails. Both places of the contact form are the same form (contact) and send to the same
destination.
Out of the box they run in demo mode: nothing is sent, and the fields are logged in the browser console. That’s fine while you build, but useless once you publish, so pick a destination before launch.
The quickest way to receive submissions
Section titled “The quickest way to receive submissions”| You want | Mode | Hosting |
|---|---|---|
| An email for every message, with no server to run | Static: a form service (Formspree, Web3Forms, Getform, Basin) | Any static host |
| Messages in your CRM, calendar tool, Slack, a spreadsheet… | Static: a webhook (Zapier, Make, n8n, Pipedream) | Any static host |
| Resend or Mailchimp directly, with no third party in between | Server: the site’s own route (below) | A host with an Astro adapter |
Most sites want static mode: it keeps the site 100% static and takes two minutes.
-
Create a form at your service and copy its endpoint URL (Formspree:
https://formspree.io/f/<id>). -
Copy the example settings and paste the URL:
Terminal window cp .env.example .envPUBLIC_FORM_ENDPOINT=https://formspree.io/f/abcdwxyzWeb3Forms also needs
PUBLIC_FORM_ACCESS_KEY. -
Restart
npm run devand send a test from the Contact page. -
If your host builds the site, put the same variable in its dashboard before deploying:
.envstays on your computer (it is not in Git). The value is written into the pages when the site builds, so rebuild after changing it.
The endpoint is public (it is in the page), which is how these services are designed to work; they filter spam on
their side. Both forms post their fields with form (contact or newsletter) and subject (the submission’s title,
“New message from the Balancee contact form” for the contact form) next to them. Details for each service are in
Forms reference.
Server mode
Section titled “Server mode”For Resend or Mailchimp without a third-party service, the forms post to a route on your own site:
-
Add the adapter for your host:
npx astro add vercel(ornetlify,node, …). -
Set
PUBLIC_FORM_MODE=server, and choose where submissions go withFORM_PROVIDER:You want Set An email for every submission FORM_PROVIDER=resend+RESEND_API_KEY,FORM_EMAIL_TO,FORM_EMAIL_FROMIt in your CRM, Slack, a spreadsheet… FORM_PROVIDER=webhook+FORM_WEBHOOK_URL(Zapier, Make, n8n, Formspree, your own API);FORM_WEBHOOK_SECRETis optionalThe sender in a Mailchimp audience FORM_PROVIDER=mailchimp+MAILCHIMP_API_KEY,MAILCHIMP_AUDIENCE_IDThe server log only, while you test FORM_PROVIDER=console(the default)Several at once work:
FORM_PROVIDER=resend,mailchimp. -
Restart
npm run devand send a test. The forms now post to/api/forms/contactand/api/forms/newsletter(src/lib/forms/route.ts, added bysrc/integrations/forms.ts); every page stays static, only that route runs on the server. -
Put the same variables in your host’s dashboard before deploying, and redeploy after changing them.
Details for each provider, what it receives, the webhook payload, Mailchimp consent settings and how to write your own provider are in Forms reference.
What the forms ask for
Section titled “What the forms ask for”The contact form (form contact, button “Submit”, title “New message from the Balancee contact form”):
| Field | Name it arrives under | Required |
|---|---|---|
| Name | Name |
yes |
| Company | Company |
yes |
Email |
yes | |
| Phone | Phone |
|
| I’m interested in … (one radio button per service) | Service (the chosen one) |
|
| Tell us about your project. | Message |
Each field has its label above it and a placeholder inside (“Jane Smith”, “Balancee & Co.”, “jane@example.com”…). The
choices of “I’m interested in …” are written in shared.json (contactForm.fields.service.options, eight in the demo,
the services’ names): add, rename or remove a service there by hand too, they are not read from the collection. The
visitor picks one or none. In server mode, Resend puts the sender’s name after the title in the email’s subject (“New
message from the Balancee contact form — Jane Smith”) and sets the reply address to the sender’s e-mail; Mailchimp stores
the name as FNAME, tags the contact with the title and keeps the rest as a note; a webhook receives every field of the
form with its label.
The newsletter box (form newsletter, title “New newsletter subscriber”) has one field, Email, required. Its
placeholder and button come from footer.newsletter in src/content/site.json; its two messages, “Thank you” and “Try
again”, from src/lib/forms/definitions.ts.
Changing the form
Section titled “Changing the form”The labels, placeholders, the error messages, the button’s three texts (“Submit”, “Thank you” and “Something went wrong”)
and the title of each submission (notification) are content: contactForm in src/content/pages/shared.json. The line
under the button, with its two links, is formLegal. A field arrives at your service under its name, so keep the names
you already map somewhere.
The form sends every field it shows, and in server mode src/lib/forms/definitions.ts reads the same list to check the
required ones again, so the list in the copy is the place to edit:
-
To make a field required, set
"required": trueon it and give it anerrormessage (to require the phone number, for example). The browser checks it before sending and, in server mode, the route checks it again. No asterisk is shown: say it in the label if you want to. A required field must be on the page: in server mode, a required field that is only in the list makes every submission fail. -
To add a field, add an entry to
fields(mind the comma between entries), for example a job title:"title": { "name": "Title", "label": "Job title", "placeholder": "COO", "type": "text", "autoComplete": "organization-title" }The types are
text(the default),email,tel,textareaandradios(withoptions). The fields are laid out by hand, so also place it in the form, insrc/components/sections/ContactForm.astro: add<FormField {...fields.title} />where it should go (withclass="md:col-span-2"for a full-width one; the fields sit two by two from tablets up). -
To remove a field, delete its entry and its
<FormField … />line. Keepemail: Resend and Mailchimp use it. -
Don’t give a real field the name
fax: it is the honeypot’s (Spam).
Testing before launch
Section titled “Testing before launch”- Submit both forms on your own site after deploying, with a real address.
- Check the destination (inbox, spreadsheet, audience) and reply to the test.
- Try a failure on purpose: point
PUBLIC_FORM_ENDPOINTat a wrong URL in a test build (or set a wrong API key in server mode), submit, and confirm the visitor sees “Something went wrong” (“Try again” in the footer) and their text is still there.
The honeypot stops the usual bots: the forms carry a hidden field named fax that a person never sees; a bot that fills
it is shown “Thank you” and nothing is sent. If you start getting spam anyway, use a form service in static mode
(Formspree, Web3Forms and Basin all include spam filtering), or add a captcha to the form component
(src/design-system/components/forms/Form.astro).
Privacy
Section titled “Privacy”Submissions go only where you point them; nothing is sent anywhere else. A message can say a lot about a person: their
name, company, e-mail and phone, and in the message whatever they write. Most countries expect you to say what happens to
that data. The demo’s Privacy Policy (/legal/privacy-policy) is a sample with placeholders: replace it with your own
(Editing the content), and choose a form service or provider that keeps the data where the law where you
work allows. The contact form has no consent checkbox; the line under its button points to your Terms of Service and
Privacy Policy. Add a field (as above) if you need explicit consent.
The forms don’t ask for marketing consent, so if you send them to Mailchimp, keep MAILCHIMP_STATUS at transactional
(the default): those contacts can get your replies, not your campaigns.