How to Use Astro Actions: Simple Guide with Examples

In Astro, actions let you handle form submissions on the server by defining functions inside a special export const actions object. You connect these actions to forms using the form element's action attribute, enabling server-side processing without client JavaScript.

Syntax

Astro actions are defined inside an export const actions object in your component or page. Each key in this object is an action name, and its value is an async function that receives the form data and returns a response.

Use the action name as the action attribute in your form to link the form submission to that server function.

astro

export const actions = {
  actionName: async ({ request }) => {
    const formData = await request.formData();
    // process formData
    return { success: true };
  }
};

---

<form method="post" action="?/actionName">
  <!-- form fields -->
  <button type="submit">Submit</button>
</form>

Example

This example shows a simple contact form using Astro actions. When the form is submitted, the server action reads the name and message, then returns a success message.

astro

---
export const actions = {
  contact: async ({ request }) => {
    const formData = await request.formData();
    const name = formData.get('name');
    const message = formData.get('message');
    // Here you could save data or send email
    return { success: true, message: `Thanks, ${name}! Your message was received.` };
  }
};
---

<form method="post" action="?/contact">
  <label for="name">Name:</label>
  <input id="name" name="name" required />

  <label for="message">Message:</label>
  <textarea id="message" name="message" required></textarea>

  <button type="submit">Send</button>
</form>

Output

<form> with fields Name and Message and a Send button; on submit, server processes and returns success message.

Common Pitfalls

• Forgetting to prefix the form action attribute with ?/ to link to the correct action.
• Not using method="post" on the form, which is required for actions.
• Trying to access form data on the client side instead of inside the server action.
• Returning non-serializable data from the action, which can cause errors.

astro

/* Wrong: Missing ?/ prefix in form action */
<form method="post" action="/contact">
  <!-- fields -->
</form>

/* Right: Correct action linking */
<form method="post" action="?/contact">
  <!-- fields -->
</form>

Quick Reference

Remember these key points when using Astro actions:

• Define actions inside export const actions as async functions.
• Use ?/actionName in form action attribute.
• Use method="post" on forms.
• Access form data with await request.formData().
• Return simple objects to send data back.

Key Takeaways

Astro actions handle server-side form submissions via async functions in an exported actions object.

Link forms to actions using the form's action attribute with a ?/ prefix and method="post".

Access form data inside actions with await request.formData() for processing.

Always return simple serializable objects from actions to avoid errors.

Avoid client-side form handling when using Astro actions to keep logic on the server.