Skip to content
Sign inJoin waitlist

Forms reference — Compose Digi Astro

Compose for Astro has one form: the contact form on the Contact page (“Send message”), <Form name="contact">. It 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 name of the <Form> / form in the payload Fields (name → label) Required
Contact Contact contact first-name First Name, last-name Last Name, email Email, phone Phone Number, message Message, services Services first-name, last-name, email

“Services” is a group of round checkboxes, one per service (the names in src/content/collections/services.json), so the visitor can tick several or none. Both names and the e-mail are required, as in the Framer template, and the e-mail must look like an e-mail address; the phone, the message and the services can be left empty.

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. The PUBLIC_ variables are read when the site is built: rebuild (or restart npm run dev) after changing them.

<Form> (design system) → browser: PUBLIC_FORM_ENDPOINT, or the demo
→ server mode: POST /api/forms/contact → deliver() → provider(s) chosen in FORM_PROVIDER

formEndpoint("contact") in src/lib/forms/endpoint.ts decides where the form posts: /api/forms/contact in server mode, else PUBLIC_FORM_ENDPOINT, else nothing (demo mode). The browser part is src/design-system/scripts/form.ts.

<Form> checks the fields when Submit is pressed: when a required field is empty or the e-mail isn’t an e-mail address, the first such field gets the focus, and each one is marked invalid and shows its message (error of the field, e.g. “Please enter a valid email address.”) until it is changed. Nothing is sent until the check passes. Without JavaScript the browser’s own 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 form posts multipart/form-data with Accept: application/json, and the service must answer with a 2xx status; any other answer (or no answer) shows “Something went wrong”.

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 (see the table above) — services once for each ticked service, nothing when none is ticked — plus form (contact) and subject (“New contact request”, for services that e-mail the submission).

The endpoint is public (it is in the page), which is how these services are designed to work; they filter spam themselves. A build with PUBLIC_FORM_ENDPOINT set sends the style guide’s sample forms nowhere: they are marked demo.

For Mailchimp or Resend without a third-party service, run the form on your server:

  1. Add the adapter for your host: npx astro add vercel (or netlify, node, …).
  2. Set PUBLIC_FORM_MODE=server and choose providers with FORM_PROVIDER.

The form then posts to POST /api/forms/contact (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, so only your own pages can submit. The route answers JSON: 200 { "status": "success" }, or 500 { "status": "error" } (404 for an unknown form, 400 when the body isn’t form data). Environment variables are read when the server runs (process.env, then the values of the build).

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, Slack workflow, 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 at once with a comma: FORM_PROVIDER=resend,mailchimp emails you and adds the contact to Mailchimp. If any of them fails, the visitor sees “Something went wrong” (their input stays in the form) and the reason is logged on the server. The providers run at the same time, so when one fails the others have usually delivered already: sending again can duplicate. Each submission carries the form’s name (form: contact) and its title (title: “New contact request”).

Variable For Needed What it is
PUBLIC_FORM_ENDPOINT static mode no (demo mode when empty) The form service’s or webhook’s URL
PUBLIC_FORM_ACCESS_KEY static mode, Web3Forms for Web3Forms Your Web3Forms access key
PUBLIC_FORM_MODE server mode no server adds the route and sends there (needs an adapter)
FORM_PROVIDER server mode no (console when missing) console, webhook, mailchimp, resend, or several, separated by commas
FORM_WEBHOOK_URL webhook yes The address that receives the POST
FORM_WEBHOOK_SECRET webhook no Sent as Authorization: Bearer <secret>; leave it empty to send no header
MAILCHIMP_API_KEY mailchimp yes Ends in your data center, e.g. …-us21
MAILCHIMP_AUDIENCE_ID mailchimp yes The audience that receives the contacts
MAILCHIMP_STATUS mailchimp no (transactional) The status of a new contact: transactional, pending or subscribed
RESEND_API_KEY resend yes Your Resend API key
FORM_EMAIL_TO resend yes The recipient, or several separated by commas
FORM_EMAIL_FROM resend yes A sender on a domain verified in Resend, e.g. Compose <forms@yourdomain.com>

A provider that needs a variable and doesn’t find it stops that submission with Missing environment variable <NAME> (see .env.example) in the server log; a name in FORM_PROVIDER that doesn’t exist does the same with Unknown FORM_PROVIDER "<name>". The visitor sees “Something went wrong” in both cases.

deliver() (src/lib/forms/deliver.ts) checks again on the server, since a browser can be bypassed. With the form’s definition from src/lib/forms/definitions.ts (made from the copy, form in src/content/pages/contact.json) it:

  1. drops the submission if the honeypot is filled (and answers success);
  2. reads each field of the form from the submitted data (trimmed); services (every checkboxes field) is read as a list of all the ticked values;
  3. answers the error state when a required field (both names, the e-mail) is empty, or when a filled-in e-mail field doesn’t look like an address;
  4. builds the submission (form, title, submittedAt, data, labels) and gives it to every provider named in FORM_PROVIDER;
  5. answers success, or the error state with the reason logged ([forms] <title> could not be delivered).
  • console: [forms] <title> followed by the submitted values (data) as an object, for example [forms] New contact request { 'first-name': 'Jane', 'last-name': 'Smith', email: 'jane@example.com', … }. In development it shows in the terminal that runs npm run dev; on a host, in its logs.
  • webhook: one POST of JSON (Content-Type: application/json) holding the whole submission, as in the payload below. An answer that isn’t a success is an error.
  • mailchimp: three calls. The sender is added or updated in the audience (email, in lower case, FNAME from first-name and LNAME from last-name, each only when filled in; MAILCHIMP_STATUS is the status of a new contact only), tagged with the form’s title, and a note is added to the profile: the title, then one “Label: value” line for each field that was filled in (the ticked services joined with commas).
  • resend: one e-mail from FORM_EMAIL_FROM to FORM_EMAIL_TO. The subject is the title followed by the sender’s name, first and last name together (“New contact request — Jane Smith”; the title alone if both are empty), the reply address is the sender’s e-mail, and the text is one “Label: value” line for each field that was filled in, then the time it was sent.
  • API key: Profile → Extras → API keys. It ends in your data center (…-us21); nothing else to configure.
  • Audience ID: Audience → Settings → Audience name and defaults.
  • Consent: new contacts are added as transactional — they can receive replies, not campaigns. Use pending to send a double opt-in email, or subscribed only if the form asks for marketing consent. Compose’s form doesn’t.
  • Merge fields: the first name (first-name) → FNAME and the last name (last-name) → LNAME, a new audience’s defaults. Change mergeFields at the top of providers/mailchimp.ts if your audience uses other tags, for example phone: "PHONE".
  • Services as tags: add "services" to tagFields in the same file to tag each contact with the services they ticked, besides the form’s title.
{
"form": "contact",
"title": "New contact request",
"submittedAt": "2026-10-20T10:48:23.256Z",
"data": {
"first-name": "Jane", "last-name": "Smith", "email": "jane@example.com", "phone": "",
"message": "We need a new brand identity and a launch campaign.", "services": ["Branding and Strategy", "Social Media Marketing"]
},
"labels": {
"first-name": "First Name", "last-name": "Last Name", "email": "Email", "phone": "Phone Number",
"message": "Message", "services": "Services"
}
}

data has a key for every field, in the order of the form, and labels the label of each. A text field left empty is ""; services is always a list of the ticked services ([] when none).

The form carries a hidden text field named fax (honeypotField in src/design-system/components/forms/form-state.ts): it is out of sight and out of the tab order, a person never fills it, and bots usually do. When it holds anything the form shows “Thank you” without sending anything (and deliver() does the same on the server), so the bot moves on; in static mode the field is left out of what is posted. Keep it as it is, and don’t give a real field the name fax.

5. Your own provider (HubSpot, Brevo, Airtable, a database…)

Section titled “5. Your own provider (HubSpot, Brevo, Airtable, a database…)”
  1. Create src/lib/forms/providers/<name>.ts exporting a FormProvider — throw to show the error state:

    import { env, valueOf, type FormProvider } from "../types";
    export const brevoProvider: FormProvider = {
    name: "brevo",
    async send(submission) {
    const response = await fetch("https://api.brevo.com/v3/contacts", {
    method: "POST",
    headers: { "api-key": env("BREVO_API_KEY"), "Content-Type": "application/json" },
    body: JSON.stringify({
    email: valueOf(submission, "email"),
    attributes: { FIRSTNAME: valueOf(submission, "first-name"), LASTNAME: valueOf(submission, "last-name") },
    updateEnabled: true,
    }),
    });
    if (!response.ok) throw new Error(`Brevo responded ${response.status}: ${await response.text()}`);
    },
    };
  2. Register it in providers/index.ts (brevo: brevoProvider).

  3. Set FORM_PROVIDER=brevo and its variables in .env.example / your host.

Helpers from types.ts: valueOf(submission, name) returns one field as text (a list joined with “, “), toLines(submission) returns "Label: value" lines for every filled field, and env(name) reads a required variable with a clear error. The form always delivers an email and both names (first-name, last-name).

  • Fields and labels live in the copy: form.fields in src/content/pages/contact.json (synced from the template’s content). name is the key services and providers receive, label is what people read above the field (and what the notification shows), placeholder is what the empty field shows, type picks the control (text, email, tel, textarea, checkboxes), required makes the field checked before sending (no asterisk is shown), error is the message shown when the check fails. The button’s three texts and the title of the notification (notification) are there too.
  • The services are the services’ names: add, rename or remove a service in src/content/collections/services.json and the checkboxes follow.
  • Required fields come from the same required flags: in server mode definitions.ts reads them and the route checks them again before it sends anything. To require another field, set required: true on it and give it an error message.
  • A new field: add it to form.fields, then place it in the form of the Contact page’s section (<FormField {...fields.<key>} />). A new checkboxes field takes its choices from options and is sent as a list on its own.
  • A new form: lay it out with <Form name="…" endpoint={formEndpoint("…")} hidden={formServiceFields()}> and <FormField>, add its definition to forms in definitions.ts for server mode and its name to FormKind in types.ts.