Forms — Catchup Astro
The inquiry form of this Astro template works as soon as you run it: Name, Email, Services, Budget, Project Timeline and Message, on the Contact page.
It checks the required fields (Name, Email, Budget and Project Timeline), shows a spinner on its 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.
Out of the box it runs 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 submission, with no server to run | Static: a form service (Formspree, Web3Forms, Getform, Basin) | Any static host |
| Submissions in your CRM, 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. The form posts its fields with form (contact) and subject (the submission’s title, “New inquiry from
the Catchup website” in the demo) 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 form posts 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 form now posts to/api/forms/contact(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 form asks for
Section titled “What the form asks for”The inquiry form on the Contact page (form contact, button “Submit Inquiry”, title “New inquiry from the Catchup
website”):
| Field | Kind | Name it arrives under | Required |
|---|---|---|---|
| Name | text | name |
yes |
email |
yes | ||
| Services | chips, one choice: Branding, Design, Development, Photography | service |
|
| Budget | a list: Under $5,000 … $20,000+ | budget |
yes |
| Project Timeline | a list: ASAP, 2–4 Weeks, 1–2 Months, Flexible | timeline |
yes |
| Message | a text area | message |
Each field shows its label above it and a placeholder inside (“Your name*”, “Estimated Budget”…); the two lists start
on their placeholder, which the visitor must replace. Under the button, a note says that submitting means agreeing to
the Terms and the Privacy Policy, with links to both legal pages (consent in contactPage).
A form service or webhook in static mode receives every field by its name and the title as subject. In server mode,
Resend puts the sender’s name after the title in the email’s subject 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, as "" when left empty, with its label.
Changing the form
Section titled “Changing the form”The labels, placeholders, choices, the button’s three texts (“Submit Inquiry”, “Thank you” and “Something went
wrong”) and the title of each submission (notification) are content: contactForm in
src/content/pages/contact.json. A field arrives at your service under its name, so keep the names you already map
somewhere. Write your own notification: the demo’s names Catchup.
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 change the choices of Services, Budget or Project Timeline, edit their
options. -
To make a field required or optional, set or remove
"required": trueon it. The browser checks it before sending and, in server mode, the route checks it again. The Services chips are drawn byChoiceChips, which takesrequiredas its own prop: to make them required, also addrequired={service.required}to<ChoiceChips …>insrc/components/sections/ContactMain.astro, or in server mode the route refuses a form the browser let through. -
To add a field, add an entry (mind the comma between entries), for example a phone number:
"phone": { "name": "phone", "label": "Phone", "placeholder": "Your phone", "type": "tel", "autoComplete": "tel" }The types are
text(the default),email,tel,url,select(withoptions; the placeholder is its empty first choice) andtextarea. The fields are laid out by hand, so also place it in the form, insrc/components/sections/ContactMain.astro: add its name to the list of field names next tofields, take it fromfieldswith the others (const { name, email, …, phone } = fields) and add<FormField {...phone} />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, its name in that list and its
<FormField … />line. Keepnameandemail: Resend and Mailchimp use them. -
Don’t give a real field the name
fax: it is the honeypot’s (Spam).
Testing before launch
Section titled “Testing before launch”- Submit the form 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” and their text is still there.
The honeypot stops the usual bots: the form carries 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. Most countries expect you to say what happens
to the data people send you, and the form collects a name, an e-mail address, a budget, a timeline and a message. The
template’s Privacy Policy (src/content/collections/legal.json) is a sample: replace it with your own, written for your
business and the law where you work.
The form doesn’t ask for marketing consent, so if you send it to Mailchimp, keep MAILCHIMP_STATUS at transactional
(the default): those contacts can get your replies, not your campaigns.