Form

What you can build

A form lets your visitors send you information, and lets your site do something useful with it. With Mosaic forms you can build things like:

• A contact form that emails you each message.
• A feedback or survey form.
• A form that collects file uploads, such as a job application with a CV.
• A search form that sends visitors to your site’s results page.

A form is built entirely from Mosaic elements, so you design and style it just like the rest of your site. When you add a Form, Mosaic starts you off with a ready-to-use contact form that you can rename, extend, and restyle.

The parts of a form

A form is made up of a Form wrapper containing two regions that are always present. You build inside both, but neither can be deleted or reordered:

• Form: the form itself, holding your fields, their labels, and the submit button. This is what the visitor fills in.
• Success screen: a confirmation area you build yourself, hidden until a submission succeeds. See Success screen.

You will find both nested inside the Form wrapper in the Navigator. Select any part to work on it.

The Success screen appears only after a submission that Mosaic handles itself succeeds, that is, when On submit is set to Actions (described below) and no redirect sends the visitor to another page first. Until then, visitors see the form.

Adding a form

Add a Form the same way you add any other element in the editor. Mosaic inserts a ready-to-use contact form, so you have a working form straight away. From there you can:

• Add, remove, and rearrange fields to collect exactly what you need.
• Choose what happens on submit, such as who gets notified.
• Style every part to match your design.

The sections below explain each of these, and the list at the end of the page links to the detailed documentation for every element and setting.

Form settings

Select the Form wrapper to open its settings, where you decide what the form does when it is submitted and how its submissions are labeled.

• On submit: how the submission is handled, either Actions or Submit to a URL. This is the most important choice, and it is covered in the next section.
• Form name: a name for the form so you can tell it apart from your other forms. It labels the form in the Form submissions screen, and is also available as a dynamic variable, handy for something like an email subject. Leave it empty and submissions read “Unlabeled form”.
• Entry name: which field labels each individual submission in the list, usually the visitor’s email address or name.

Form name and Entry name shape how your saved submissions read in the WordPress admin. See Form submissions for the admin side.

How a form is submitted

The On submit setting gives every form one of two jobs, and a form uses one or the other:

• Actions: Mosaic receives the submission, validates it, runs its spam protection, and then carries out the actions you set up, such as sending an email, redirecting the visitor, or running a search. This is the default and the path most forms use. The actions are covered on the Actions page.
• Submit to a URL: the form hands the submission straight to a web address you choose, outside Mosaic. Use this only for simple handoffs to an endpoint you already trust. It is described below.

While you are editing, switching between the two is safe: your setup for each is kept, so you can flip to Submit to a URL to compare and flip back to Actions without losing your work. Only the option you have selected is saved and used on your live form, so if you reload the editor the settings for the other option are lost.

Validation

Before a form is sent, the browser checks it against the rules on each field, such as a required field left empty or an email address in the wrong format, and stops the submission until they are fixed. When On submit is set to Actions, Mosaic then checks everything again on the server, which is the authoritative check a visitor cannot skip.

By default, validation problems appear in the browser’s own bubble. Add an Error message element to show your own styled messages, next to the field or for the whole form, instead.

Submit to a URL

Setting On submit to Submit to a URL is the escape hatch for endpoints Mosaic does not model. Instead of running actions, the form posts its fields straight to a web address you choose. Mosaic does not process or store the submission, and it does not know what the destination does with the data. This mode has these settings:

• Action URL: the web address the form submits to.
• Target: where the destination opens, such as the same tab (Self) or a new tab (Blank).
• Method: how the data is sent, Get or Post.
• Encoding: how the form data is encoded for the destination. Set this to whatever your target endpoint expects.

Spam protection

Every form handled with Actions is protected by a built-in honeypot that quietly filters out automated spam, with nothing for you to set up. For stronger protection you can add a Cloudflare Turnstile or Google reCAPTCHA element to the form. See Spam protection.

Animating on submit

Mosaic’s interaction system includes a Form submit trigger that plays an interaction when a submission succeeds. Use it to run a tracking or analytics snippet on a successful sign-up, or to animate the form as it clears. See Interactions for how to set up a trigger.

Explore the form documentation

Each part of the form system has its own page. Start here to find the one you need.

Designing the form

• Fields & field groups: the wrappers (Field, Choice field, Field set) that hold your inputs and keep them labeled and organized.
• Text inputs: single-line inputs (text, email, phone, URL, number, date) and multi-line text areas.
• Select: a dropdown of options.
• Radio & checkbox: choice groups where visitors pick one option or several.
• File upload: let visitors attach files.
• Hidden input: submit a value the visitor never sees.
• Default values: prefill an input from a fixed value, the page address, and more.
• Submit button: the button that sends the form, with an optional loading state.
• Error message: show styled validation and error messages in place of the browser’s default.
• Success screen: the confirmation area shown after a successful submission.

Handling the submission

• Actions: what the form does on submit, including the Email, Redirect, and Search actions and running an action only when a condition matches.
• Spam protection: the built-in honeypot and the optional Cloudflare Turnstile and Google reCAPTCHA elements.
• Form submissions: review what your forms collect, retry a failed action, and manage stored submissions.

Setting up form emails

This guide walks you through setting up your form to email you every time someone submits it, one step at a time. By the end you’ll have a working contact form that sends a notification to your inbox, plus a short troubleshooting section in case an email doesn’t arrive.

Step 1: Add a Form element

In the editor, add a Form element to your page the same way you add any other element. Mosaic drops in a ready-to-use contact form with a name field, an email field, a message field, and a submit button, so you have something working straight away. Add, remove, or rename fields until the form collects exactly what you need.

Step 2: Open the form’s actions

Select the Form element in the Navigator to open its settings. Under On submit, make sure Actions is selected (this is the default). Actions are the things your form does when a submission succeeds.

Next to the actions list, press the + button to add a new action, and choose Email from the list of action types. The Email action opens in its own window with two tabs: General (the settings below) and Condition (optional, covered in Step 9).

Step 3: Set who receives the email (To email)

In To email, enter the address that should receive the notification. This defaults to your site’s admin address, so you can leave it as is or change it.

• To send to more than one person, separate the addresses with commas.
• Each entry can be a plain address (you@example.com) or include a name (John Doe <johndoe@example.com>).

Step 4: Set the sender (From name and From email)

• From email: the safest choice is to leave this empty, so WordPress uses its own default sender. This is usually the most reliable option for delivery. If you do set an address, use one on your own domain, because mail providers reject email that claims to come from a domain that isn’t yours.
• From name: the name shown next to the sender. It only applies when you’ve also set a From email; if From email is empty, WordPress’s default name is used.

Step 5: Write the subject

In Subject, enter the subject line for the email. If you leave it empty, Mosaic uses “New form submission on” followed by your site’s name.

You can make the subject dynamic, for example by inserting the form name so you can tell at a glance which form was submitted.

Step 6: Write the message

In Message, write the body of the email. It starts empty, so this is where you decide what the notification says.

Use dynamic variables to include what the visitor actually submitted. Open the variable picker on the field and insert:

• Individual field values, referenced by field name.
• The All fields variable, which outputs every submitted field as a readable list, handy for including the whole submission at once.
• The form name, request details (such as the visitor’s IP or the page the form was on), and more.

Anything a visitor typed is inserted as plain text, so submitted HTML or scripts show up as text rather than running. Your notifications are safe by default.

Step 7: Set the extra options (optional)

Select More options for the rest of the settings:

• Content type: send the message as HTML (the default, so links and formatting display) or Plain text.
• Reply to email: set this to the visitor’s email field so you can reply straight back to them.
• CC and BCC: extra recipients, in the same format as To email.
• Attachments: attach the files from one or more File upload fields to the email. Only file fields appear here.

Step 8: Add a condition (optional)

Switch to the Condition tab if you only want this email to send in certain cases, for example only when a checkbox is ticked or a particular option is chosen. Leave it empty and the action always runs.

Step 9: Save the action

Select Apply form action to save it. You can add more actions if you like, such as a Redirect to a thank-you page, and they run in the order they appear in your list.

Step 10: Set up an SMTP plugin so your emails deliver

Mosaic hands the email to WordPress, which sends it using your hosting’s mail setup. On many hosts, mail sent this way is unreliable: it can land in spam or not send at all. To make sure your form emails actually arrive, set up an SMTP plugin. You only do this once, and it fixes email for your whole site.

1. Install a free SMTP plugin, such as WP Mail SMTP or FluentSMTP.
2. Start the setup wizard. After activating, the plugin offers to walk you through the setup. Click the button to start it and follow the screens.
3. Pick a mail service when it asks. The wizard shows a list of services it can send your mail through, such as Brevo, SendGrid, or Mailgun. If you’re not sure which to choose, Brevo is a good, beginner-friendly option. Pick one and click Continue.
4. Connect your account. The wizard tells you exactly what to copy from the service (usually one key) and shows you where to paste it. Just follow its instructions on screen.
5. Let the wizard finish. It may ask you to add a couple of settings to your website’s domain so mail providers trust your emails. The service shows you what these are. If this part looks technical, don’t worry: send those details to your hosting company and ask them to add them for you. It takes them a few minutes.
6. Send a test email. The plugin has a Send a Test Email button. Send one to yourself, and when it arrives, you’re all set.

Step 11: Test your form

Open your published page, fill in the form, and submit it. You should see the success screen, and the notification should arrive in the inbox you set in Step 3. Your submission is also saved under Form submissions in the WordPress admin.

---

Troubleshooting

If your form submits successfully but the email doesn’t arrive, work through these checks. In almost every case the form is fine and the issue is with how your site sends mail.

Is your submission being saved?

Check Form submissions in the WordPress admin. If your test submission is listed there, the form captured everything correctly and the only thing that failed is the email delivery. That points to your site’s mail setup, not the form.

Does your site send any email at all?

Trigger a password reset for your own account: on your login page, choose Lost your password? and enter your admin email.

• The reset email doesn’t arrive (check spam too): your site isn’t sending mail at all. This is a hosting issue. Set up an SMTP plugin (Step 10) to fix it.
• The reset email arrives but form emails don’t: your site can send mail, so check the Email action’s settings.

Common causes

• No SMTP plugin set up. This is the most common cause. Many hosts don’t send WordPress mail reliably on their own, which is why messages arrive only sometimes, or not at all. Setting up an SMTP plugin (Step 10) resolves this for the whole site.
• The email is in spam. Always check your spam or junk folder before assuming it was lost. An SMTP plugin with authenticated DNS records (SPF and DKIM) is what stops this.
• The From email is on a domain you don’t control. If you set a From address on a free provider (like a Gmail address) or a domain your SMTP setup isn’t authorized to send from, receiving servers reject it. Leave From email empty, or use an address on your own domain.
• No valid recipient. Make sure the To email in the action is a real address. If it was cleared, or filled from a dynamic variable that came back empty, the email has nowhere to go.

Retrying a failed email

Because each submission is saved before the email is sent, nothing is lost while you fix delivery. Once your mail is working, open Form submissions, find any submission flagged as not fully completed, and retry the email action. It re-sends using the same details it had at submission time.