# Forms (Contact, Volunteer, Fundraise, Newsletter)

## Forms

**Files:** `src/config/config.toml`, form fields in content files · **Skill level:** Beginner

Givo is a static site: it has no server of its own to receive messages. Each form sends its answers to a form service you choose, which emails them to you or keeps them in a dashboard. You set that service once in `config.toml`. The donation form is the exception: it sends to your payment provider, set in the donate file.

### The Forms And Where They Send
| Form | Where it appears | Fields are in | Sends to |
| --- | --- | --- | --- |
| Contact | `/contact/` | `src/content/sections/<language>/contact-section.md`, and the `contactSection` block in `src/content/contact/<language>/-index.md` | `contactFormAction` |
| Volunteer sign-up | `/volunteer/` | `form` in `src/content/sections/<language>/volunteer-section.md` | `contactFormAction` |
| Fundraiser registration | `/fundraise/` | the `contactSection` block in `src/content/pages/<language>/fundraise.md` | `contactFormAction` |
| Donation | `/donate/`, `/tribute/` | `form` in `donate-section.md`; where it sends in `src/content/donate/<language>/-index.md` | `form.endpoint` or `form.processorUrl` in the donate file |
| Newsletter signup | every footer layout, the stories pages, the CTA `newsletter` layout, `/home-community/` | `subscription` in `src/i18n/<language>.json` | `[settings.subscription] formAction` (Mailchimp) |

Every form except the donation form and the newsletter uses the same provider, `contactFormProvider`. The donation form has its own guide: [Donation Form](/givo/customization/donation-form/). Job pages link to the address in each role's `applyUrl`, or to your organization email when it is empty.

### Connect The Forms
The theme ships with placeholder addresses. Until you replace them, messages go nowhere: `npm run dev` shows a warning inside each form, and both `npm run dev` and `npm run build` print a `[forms]` warning in the terminal. Visitors of a deployed site never see the notice, so check the terminal before you deploy.

Pick a provider and set both lines in `[settings]` of `config.toml`:

<Tabs>
  <TabItem label="Formsubmit (default)">

    Free, no account. Messages arrive by email as a table.

    ```toml
    [settings]
      contactFormAction   = "https://formsubmit.co/you@your-domain.org"
      contactFormProvider = "formsubmit.co"
    ```

    The first message triggers an **activation email** from Formsubmit. Open it and confirm, or later messages won't be delivered.

  </TabItem>
  <TabItem label="Formspree">

    Create a form at [formspree.io](https://formspree.io/) and copy its endpoint. Messages appear in your Formspree dashboard, and Formspree can email them to you.

    ```toml
    [settings]
      contactFormAction   = "https://formspree.io/f/your-form-id"
      contactFormProvider = "formspree"
    ```

  </TabItem>
  <TabItem label="Netlify Forms">

    Only when the site is hosted on Netlify. Netlify detects the forms at deploy time.

    ```toml
    [settings]
      contactFormAction   = "/"
      contactFormProvider = "netlify"
    ```

    Turn on form detection in the Netlify dashboard (**Forms**), deploy, and send a test message. Submissions appear in the dashboard and can be forwarded by email.

  </TabItem>
</Tabs>

After launch, send one real message from each form on the live site to make sure it arrives.

<Aside type="caution">
  The forms post to the real address even while you work with `npm run dev`.
  Use your own address before you test, and keep test messages short.
</Aside>

### The Newsletter (Mailchimp)
<Steps>

1. In Mailchimp, open **Audience** → **Signup forms** → **Embedded forms**, and copy the URL in `<form action="...">` from the embed code.
2. Paste it as `formAction` in `[settings.subscription]` of `config.toml`, in place of the placeholder with `YOUR_USER_ID` and `YOUR_LIST_ID`.
3. The embed code writes `&amp;` between parameters: change each one to a plain `&`.

</Steps>

```toml
[settings.subscription]
  enable     = true   # false hides every signup form and the newsletter section
  title      = ""     # empty: subscription.title in src/i18n/<language>.json
  note       = ""     # empty: subscription.note in src/i18n/<language>.json
  formAction = "https://your-account.us1.list-manage.com/subscribe/post?u=YOUR_USER_ID&id=YOUR_LIST_ID&f_id=YOUR_FORM_ID"
  mailchimpTagValue = ""   # optional Mailchimp tag id added to every signup
```

Mailchimp's bot field is added for you from the `u` and `id` in the URL. The messages (subscribing, success, already subscribed, errors), the title, and the consent line are in `subscription` of `src/i18n/<language>.json`. `title` and `note` in `[settings.subscription]` replace them in every language. With `enable = false`, the CTA `newsletter` layout falls back to its `default` look.

### Change The Fields
The contact and fundraiser forms are written the same way: a `form` with an `emailSubject`, a `submitButton`, an optional `note`, and a list of `inputs`. For the contact page, edit `form` in `src/content/sections/<language>/contact-section.md`:

```yaml
form:
  emailSubject: "New message from the website" # subject of the email the provider sends you
  submitButton:
    enable: true
    label: "Send message"
  note: "We use your details only to reply. [Privacy policy](/privacy-policy/)"
  inputs:
    - label: "Name"
      name: "Name"            # the field name in the message you receive
      icon: "User"            # leading icon (Lucide); empty hides it
      placeholder: "Your name"
      required: true
      halfWidth: true         # two fields per row on wider screens
    - label: "Message"
      name: "Message"
      tag: "textarea"
      rows: "5"
      required: true
```

| Field type | How to write it |
| --- | --- |
| Text | No `type`, or `type: "text"` |
| Email, phone, number, date, web address | `type: "email"`, `"tel"`, `"number"`, `"date"`, or `"url"` |
| Long text | `tag: "textarea"` and `rows` |
| Radio buttons | `type: "radio"`, one item per choice, with the same `name` and `group`; the first carries `groupLabel` (the question) |
| Checkboxes | `type: "checkbox"`, one item per choice, with a shared `group` |
| Dropdown | `dropdown:` with `type` (`select` or `search`) and `items` (`label`, `value`, optional `selected` and `hint`). `source: "causes"` adds one option per published cause |

Other options: `placeholder`, `required`, `defaultValue`, `value`, `checked`, `hint`, `min`, and `id`. The full list is `inputFieldSchema` in `src/sections.schema.ts`. A dropdown item's `hint` shows a line of Markdown under the field while it is chosen, as the "Getting help for me or my family" topic does.

**Topics from a link.** The contact form's **Topic** dropdown has `queryParam: "topic"`, so `/contact/?topic=events` opens the form with "An event" chosen. The theme uses this for events without a `registerUrl` (`events`), job pages (`jobs`), and the partners page (`partnerships`). Keep those `value`s if you rename the topics.

The volunteer form is simpler: its fields are named keys (`name`, `email`, `phone`, `roles`, `days`, `message`, `consent`) under `form:` in `volunteer-section.md`. Remove `phone` or `message` to leave them out. See [Volunteer & Fundraise](/givo/customization/volunteer-fundraise/).

### Success And Error Messages
In the contact and fundraiser forms, the last two items of `inputs` are not fields. The one with `note: success` holds the message shown after a message is sent; the one with `note: deprecated` the message shown when sending fails. Edit their `content` and keep their `parentClass`:

```yaml
    - note: success
      parentClass: "hidden text-sm message success"
      content: "Thank you. Your message is with the right team, and we reply within two working days." # sample promise
    - note: deprecated
      parentClass: "hidden text-sm message error"
      content: "That didn't send. Email {email} or call {phone}." # {phone} {email} from [organization]
```

`{phone}` and `{email}` are filled in from `[organization]` in `config.toml`. Make the success message a promise you keep. The volunteer form has `success` and `error` keys instead. The field error message ("Check this field.") is under `form` in `src/i18n/<language>.json`.

Without JavaScript, every form still sends: it posts straight to the provider, which shows its own confirmation page.

### Spam Protection
The contact, volunteer, and fundraiser forms have two built-in traps, with no captcha to solve (the newsletter uses Mailchimp's own hidden bot field):

- **A hidden field** that people never see but bots fill in. Its name matches your provider: `_honey` (Formsubmit), `_gotcha` (Formspree), or `bot-field` (Netlify).
- **A time trap**: a form sent less than 4 seconds after the visitor first touched it is dropped without a request.

Your provider may filter spam on top of this: check its settings.

### Privacy
Each form's `note` links to your privacy policy, and the volunteer and donation forms have a consent line. Keep them, point the links at your real pages, and list your form provider and payment provider in `src/content/pages/<language>/privacy-policy.md`.

The section files have no schema, so `npm run astro-check` doesn't report a mistyped option there. Open each form, fill it in, and send a test after each change.

### Do It With AI
```text
Connect my forms to [Formsubmit with EMAIL | Formspree with form ID | Netlify Forms]: set
contactFormAction and contactFormProvider in src/config/config.toml following its comments. Set
the Mailchimp URL [URL] as formAction in [settings.subscription], with every &amp; changed to &.
Then run npm run dev and tell me if any [forms] warning is left.
```

```text
Change the contact form in contact-section.md, in every language folder of src/content/sections/,
to ask for: [FIELDS]. Keep the form structure, the Topic dropdown with queryParam "topic" and the
values events, jobs, and partnerships, the note with the privacy link, and the two message items
at the end of inputs (note: success and note: deprecated).
```