Svelte Form Actions

Process HTML form submissions server-side using SvelteKit actions with progressive enhancement via use:enhance

When to Use

• You need to handle form submissions in SvelteKit with server-side validation and database writes
• You want forms to work without JavaScript (progressive enhancement) and enhance with JS when available
• You are implementing login, registration, CRUD mutations, or any POST-based interaction
• You need to return validation errors back to the page without a full redirect

Instructions

Defining actions:

1. Export an

   actions

   object from

   +page.server.ts

   . The default action handles forms with no

   action

   attribute:

// src/routes/contact/+page.server.ts
import { fail, redirect } from '@sveltejs/kit';
import type { Actions } from './$types';

export const actions: Actions = {
  default: async ({ request, locals }) => {
    const data = await request.formData();
    const email = data.get('email') as string;
    const message = data.get('message') as string;

    if (!email || !message) {
      return fail(400, { email, error: 'All fields are required' });
    }

    await sendEmail({ email, message });
    redirect(303, '/contact/success');
  },
};

2. Use named actions when a page has multiple forms:

export const actions: Actions = {
  login: async ({ request }) => {
    /* ... */
  },
  logout: async ({ cookies }) => {
    cookies.delete('session', { path: '/' });
    redirect(303, '/');
  },
};

Target a named action with the

action

<form method="POST" action="?/login">
  <form method="POST" action="?/logout"></form>
</form>

Reading form data:

3. Always use

   request.formData()

   — it handles multipart/form-data (file uploads) and application/x-www-form-urlencoded:

const data = await request.formData();
const name = data.get('name') as string;
const avatar = data.get('avatar') as File;

Returning errors and data:

4. Use

   fail(statusCode, data)

   to return validation errors. The page re-renders without redirect; data is available via

   form

   prop:

if (!email.includes('@')) {
  return fail(422, { email, emailError: 'Invalid email address' });
}

<!-- +page.svelte -->
<script lang="ts">
  import type { ActionData } from './$types'
  let { form }: { form: ActionData } = $props()
</script>

<form method="POST">
  <input name="email" value={form?.email ?? ''} />
  {#if form?.emailError}
    <p class="error">{form.emailError}</p>
  {/if}
  <button>Submit</button>
</form>

Progressive enhancement with use:enhance:

5. Add

   use:enhance

   to a form to intercept submission with JavaScript, preventing full-page reloads while keeping the no-JS fallback:

<script lang="ts">
  import { enhance } from '$app/forms'
</script>

<form method="POST" use:enhance>
  <input name="title" />
  <button>Save</button>
</form>

6. Customize the enhancement callback for loading states and side effects:

<script lang="ts">
  import { enhance } from '$app/forms'

  let loading = $state(false)
</script>

<form method="POST" use:enhance={() => {
  loading = true
  return async ({ result, update }) => {
    loading = false
    if (result.type === 'success') {
      await update()  // re-runs load function
    }
  }
}}>
  <button disabled={loading}>
    {loading ? 'Saving...' : 'Save'}
  </button>
</form>

File uploads:

7. Handle file uploads —

   enctype

   is set automatically when using

   use:enhance

   , but set it explicitly for no-JS fallback:

<form method="POST" enctype="multipart/form-data" use:enhance>
  <input type="file" name="avatar" accept="image/*" />
  <button>Upload</button>
</form>

// +page.server.ts
const avatar = data.get('avatar') as File;
if (avatar.size > 5_000_000) return fail(400, { error: 'File too large' });
const buffer = Buffer.from(await avatar.arrayBuffer());
await uploadToStorage(buffer, avatar.name);

Details

Action result types:

form

success

{ type: 'success', data: ... }

failure

fail(status, data)

{ type: 'failure', status, data: ... }

redirect

redirect()

error

Progressive enhancement — how it works:

Without

use:enhance

use:enhance

fetch

Validation libraries:

Use Zod or Valibot for structured validation in actions:

import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

export const actions: Actions = {
  default: async ({ request }) => {
    const formData = await request.formData();
    const result = schema.safeParse(Object.fromEntries(formData));
    if (!result.success) {
      return fail(422, { errors: result.error.flatten().fieldErrors });
    }
    // result.data is typed and validated
  },
};

Cookies in actions:

Actions have full access to the

cookies

default: async ({ request, cookies }) => {
  const { token } = await authenticate(formData)
  cookies.set('session', token, {
    path: '/',
    httpOnly: true,
    sameSite: 'lax',
    secure: true,
    maxAge: 60 * 60 * 24 * 7  // 1 week
  })
  redirect(303, '/dashboard')
}

Source

https://kit.svelte.dev/docs/form-actions

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.