Skip to content
Sign inJoin waitlist

Forms — Kendi Astro

The forms of this Astro template work as soon as you run it: the contact form and the newsletter sign-up.

The newsletter appears in three places: Home’s hero, the sidebar’s “Newsletter” card (Home and every post) and the “Stay updated with our letter” band above the footer (every page but the legal pages and the 404). The contact form is on Contact. Each form checks the required fields, shows a spinner 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 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. One destination serves both forms; every submission says which form it came from, so you can tell them apart in your inbox or tool.

You want Mode Hosting
Subscribers in your newsletter tool, messages by email, with no server to run Static: a form service (Formspree, Web3Forms, Getform, Basin) or a webhook (Zapier, Make, n8n, Pipedream) that passes sign-ups on to Mailchimp, Brevo, Beehiiv… Any static host
Mailchimp or Resend 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.

  1. Create a form at your service and copy its endpoint URL (Formspree: https://formspree.io/f/<id>).

  2. Copy the example settings and paste the URL:

    Terminal window
    cp .env.example .env
    PUBLIC_FORM_ENDPOINT=https://formspree.io/f/abcdwxyz

    Web3Forms also needs PUBLIC_FORM_ACCESS_KEY.

  3. Restart npm run dev and send a test from each form.

  4. If your host builds the site, put the same variable in its dashboard before deploying: .env stays 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 to the same endpoint, with form (newsletter or contact) and subject (“New newsletter subscriber”, “New contact message”) next to the fields. Details for each service are in Forms reference.

For Mailchimp or Resend without a third-party service, the forms post to a route on your own site:

  1. Add the adapter for your host: npx astro add vercel (or netlify, node, …).

  2. Set PUBLIC_FORM_MODE=server, and choose where submissions go with FORM_PROVIDER:

    You want Set
    Subscribers in a Mailchimp audience FORM_PROVIDER=mailchimp + MAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID; set MAILCHIMP_STATUS to pending or subscribed to send them your newsletter (consent)
    An email for every submission FORM_PROVIDER=resend + RESEND_API_KEY, FORM_EMAIL_TO, FORM_EMAIL_FROM
    It in your CRM, Slack, a spreadsheet… FORM_PROVIDER=webhook + FORM_WEBHOOK_URL (Zapier, Make, n8n, Formspree, your own API); FORM_WEBHOOK_SECRET is optional
    The server log only, while you test FORM_PROVIDER=console (the default)

    Several at once work: FORM_PROVIDER=mailchimp,resend.

  3. Put the variables in your host’s dashboard and deploy. The forms post to /api/forms/newsletter and /api/forms/contact; every page stays static.

Without an adapter the build stops with NoAdapterInstalled. What each provider receives, the webhook payload, Mailchimp’s merge fields and how to write your own provider (Brevo, ConvertKit, Beehiiv…) are in Forms reference.

The newsletter (form: newsletter, title “New newsletter subscriber”, button “Subscribe”):

Field Name it arrives under Required
Email email yes
The consent box (the sidebar card and the band only) consent (on when ticked; yes in server mode)

The contact form on Contact (form: contact, title “New contact message”, button “Submit”):

Field Name it arrives under Required
Name Name yes
Email Email yes
Message Message yes

An e-mail that doesn’t look like an address shows the error without sending.

The labels, placeholders, the button’s three texts and the title of each submission are content:

Form Copy Layout
Newsletter newsletter.form in src/content/site.json (the band and the sidebar card), hero.subscribe in src/content/pages/home.json (Home’s hero) SubscribeForm.astro in src/design-system/components/forms/
Contact form in src/content/pages/contact.json src/components/sections/ContactSection.astro

A field arrives at your service under its name, so keep the names you already map somewhere.

  • To make a field optional, remove "required": true from it. The browser checks required fields before sending, and server mode checks them again (src/lib/forms/definitions.ts); the submit button stays faded until they are filled.

  • To add a field, add an entry to form.fields in contact.json, for example a subject:

    "subject": { "name": "Subject", "label": "Subject", "placeholder": "What is it about?" }

    The types are text (the default), email, tel and textarea. Then place it in the form: <FormField {...toField(fields.subject)} /> in src/components/sections/ContactSection.astro.

  • To remove a field, delete its entry and its <FormField … /> line.

  • Don’t give a real field the name fax: it is the honeypot’s (Spam).

  • Submit each form on your own site after deploying, with a real address: a newsletter sign-up from Home, the sidebar and the band, and a contact message.
  • Check the destination (inbox, audience, spreadsheet) and reply to the test message.
  • Try a failure on purpose: a wrong endpoint or API key, submit, and confirm the visitor sees “Something went wrong” and their text is still there.

The honeypot stops the usual bots: every 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. Form services filter spam on their side too. If you start getting spam anyway, turn on the service’s captcha, or use Mailchimp’s double opt-in (MAILCHIMP_STATUS=pending).

Submissions go only where you point them; nothing is sent anywhere else, and the site itself stores nothing. The newsletter forms in the sidebar and the band carry a consent line that links your Terms of Service and Privacy Policy; Home’s hero form has none. The legal texts are generic samples with placeholders ([Your Company Name] …): fill them in and make the Privacy Policy say how you handle subscribers and messages — and which form service receives them — before you collect any (Editing the content).

Mailchimp adds new contacts as transactional unless you set MAILCHIMP_STATUS: they can get your replies, not your campaigns. A newsletter needs consent to send to, so set pending (Mailchimp emails a confirmation link first: double opt-in, the safest choice) or subscribed (only if your form’s wording is a clear opt-in where you publish). In server mode the provider applies to both forms, so with Mailchimp the people who write to you also land in the audience, tagged “New contact message”; if you don’t want that, use a webhook and route each form where it belongs.