build-forms.mdx

title	description	i18nReady	type
Build HTML forms in Astro pages	Learn how to build HTML forms and handle submissions in your frontmatter.	true	recipe

import { Steps } from '@astrojs/starlight/components';

In SSR mode, Astro pages can both display and handle forms. In this recipe, you'll use a standard HTML form to submit data to the server. Your frontmatter script will handle the data on the server, sending no JavaScript to the client.

Prerequisites

• A project with SSR (output: 'server') enabled

Recipe

1. Create or identify a `.astro` page which will contain your form and your handling code. For example, you could add a registration page:

```astro title="src/pages/register.astro"
---
---
<h1>Register</h1>
```

2. Add a <form> tag with some inputs to the page. Each input should have a name attribute that describes the value of that input.

   Be sure to include a <button> or <input type="submit"> element to submit the form.

   ---
   ---
   <h1>Register</h1>
   <form>
     <label>
       Username:
       <input type="text" name="username" />
     </label>
     <label>
       Email:
       <input type="email" name="email" />
     </label>
     <label>
       Password:
       <input type="password" name="password" />
     </label>
     <button>Submit</button>
   </form>

3. Use validation attributes to provide basic client-side validation that works even if JavaScript is disabled.

   In this example,

   • required prevents form submission until the field is filled.
   • minlength sets a minimum required length for the input text.
   • type="email" also introduces validation that will only accept a valid email format.

   ---
   ---
   <h1>Register</h1>
   <form>
     <label>
       Username:
       <input type="text" name="username" required />
     </label>
     <label>
       Email:
       <input type="email" name="email" required />
     </label>
     <label>
       Password:
       <input type="password" name="password" required minlength="6" />
     </label>
     <button>Submit</button>
   </form>

   :::tip You can add custom validation logic that refers to multiple fields using a <script> tag and the Constraint Validation API.

   To write complex validation logic more easily, you can build your form using a frontend framework and choose a form library like React Hook Form or Felte. :::

4. The form submission will cause the browser to request the page again. Change the form's data transfer method to POST to send the form data as part of the Request body, rather than as URL parameters.

   ---
   ---
   <h1>Register</h1>
   <form method="POST">
     <label>
       Username:
       <input type="text" name="username" required />
     </label>
     <label>
       Email:
       <input type="email" name="email" required />
     </label>
     <label>
       Password:
       <input type="password" name="password" required minlength="6" />
     </label>
     <button>Submit</button>
   </form>

5. Check for the POST method in the frontmatter and access the form data using Astro.request.formData(). Wrap this in a try ... catch block to handle cases when the POST request wasn't sent by a form and the formData is invalid.

   ---
   if (Astro.request.method === "POST") {
     try {
       const data = await Astro.request.formData();
       const name = data.get("username");
       const email = data.get("email");
       const password = data.get("password");
       // Do something with the data
     } catch (error) {
       if (error instanceof Error) {
         console.error(error.message);
       }
     }
   }
   ---
   <h1>Register</h1>
   <form method="POST">
     <label>
       Username:
       <input type="text" name="username" required />
     </label>
     <label>
       Email:
       <input type="email" name="email" required />
     </label>
     <label>
       Password:
       <input type="password" name="password" required minlength="6" />
     </label>
     <button>Submit</button>
   </form>

6. Validate the form data on the server. This should include the same validation done on the client to prevent malicious submissions to your endpoint and to support the rare legacy browser that doesn't have form validation.

   It can also include validation that can't be done on the client. For example, this example checks if the email is already in the database.

   Error messages can be sent back to the client by storing them in an errors object and accessing it in the template.

   ---
   import { isRegistered, registerUser } from "../../data/users"
   import { isValidEmail } from "../../utils/isValidEmail";
   
   const errors = { username: "", email: "", password: "" };
   if (Astro.request.method === "POST") {
     try {
       const data = await Astro.request.formData();
       const name = data.get("username");
       const email = data.get("email");
       const password = data.get("password");
       if (typeof name !== "string" || name.length < 1) {
         errors.username += "Please enter a username. ";
       }
       if (typeof email !== "string" || !isValidEmail(email)) {
         errors.email += "Email is not valid. ";
       } else if (await isRegistered(email)) {
         errors.email += "Email is already registered. ";
       }
       if (typeof password !== "string" || password.length < 6) {
         errors.password += "Password must be at least 6 characters. ";
       }
       const hasErrors = Object.values(errors).some(msg => msg)
       if (!hasErrors) {
         await registerUser({name, email, password});
         return Astro.redirect("/login");
       }
     } catch (error) {
       if (error instanceof Error) {
         console.error(error.message);
       }
     }
   }
   ---
   <h1>Register</h1>
   <form method="POST">
     <label>
       Username:
       <input type="text" name="username" />
     </label>
     {errors.username && <p>{errors.username}</p>}
     <label>
       Email:
       <input type="email" name="email" required />
     </label>
     {errors.email && <p>{errors.email}</p>}
     <label>
       Password:
       <input type="password" name="password" required minlength="6" />
     </label>
     {errors.password && <p>{errors.password}</p>}
     <button>Register</button>
   </form>