Skip to content

Build forms with API routes

An HTML form causes the browser to refresh the page or navigate to a new one. To send form data to an API endpoint instead, you must intercept the form submission using JavaScript.

This recipe shows you how to send form data to an API endpoint and handle that data.

Prerequisites

Section titled Prerequisites

Recipe

Section titled Recipe

  1. Create a POST API endpoint at /api/feedback that will receive the form data. Use request.formData() to process it. Be sure to validate the form values before you use them.

    This example sends a JSON object with a message back to the client.

    src/pages/api/feedback.ts
    import type { APIRoute } from "astro";
    

    export const POST: APIRoute = async ({ request }) => {
      const data = await request.formData();
      const name = data.get("name");
      const email = data.get("email");
      const message = data.get("message");
      // Validate the data - you'll probably want to do more than this
      if (!name || !email || !message) {
        return new Response(
          JSON.stringify({
            message: "Missing required fields",
          }),
          { status: 400 }
        );
      }
      // Do something with the data, then return a success response
      return new Response(
        JSON.stringify({
          message: "Success!"
        }),
        { status: 200 }
      );
    };

  2. Create a form component using your UI framework. 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.

    src/components/FeedbackForm.tsx
    export default function Form() {
      return (
        <form>
          <label>
            Name
            <input type="text" id="name" name="name" required />
          </label>
          <label>
            Email
            <input type="email" id="email" name="email" required />
          </label>
          <label>
            Message
            <textarea id="message" name="message" required />
          </label>
          <button>Send</button>
        </form>
      );
    }

  3. Create a function that accepts a submit event, then pass it as a submit handler to your form.

    In the function:

    • Call preventDefault() on the event to override the browser’s default submission process.
    • Create a FormData object and send it in a POST request to your endpoint using fetch().
    src/components/FeedbackForm.tsx
    import { useState } from "preact/hooks";
    

    export default function Form() {
      const [responseMessage, setResponseMessage] = useState("");
    

      async function submit(e: SubmitEvent) {
        e.preventDefault();
        const formData = new FormData(e.target as HTMLFormElement);
        const response = await fetch("/api/feedback", {
          method: "POST",
          body: formData,
        });
        const data = await response.json();
        if (data.message) {
          setResponseMessage(data.message);
        }
      }
    

      return (
        <form onSubmit={submit}>
          <label>
            Name
            <input type="text" id="name" name="name" required />
          </label>
          <label>
            Email
            <input type="email" id="email" name="email" required />
          </label>
          <label>
            Message
            <textarea id="message" name="message" required />
          </label>
          <button>Send</button>
          {responseMessage && <p>{responseMessage}</p>}
        </form>
      );
    }

  4. Import and include your <FeedbackForm /> component on a page. Be sure to use a client:* directive to ensure that the form logic is hydrated when you want it to be.

    src/pages/index.astro
    ---
    import FeedbackForm from "../components/FeedbackForm"
    ---
    <FeedbackForm client:load />