x-sveltekit-action header for fetch
When using custom fetch to POST data, include the header 'x-sveltekit-action': 'true' to route the request to a +page.server.js action instead of a +server.js endpoint.
Svelte · SvelteKit · all subjects
form-actions
58 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Form actions vs +server.js endpoints
Form actions are the preferred way to send data to the server since they can be progressively enhanced. You can also use +server.js files to expose APIs, but these cannot be progressively enhanced with use:enhance.
GET forms in SvelteKit
Forms with method="GET" (or no method specified) are treated like <a> elements and use the client-side router instead of full page navigation. They invoke load functions but not actions. You can set data-sveltekit-reload, data-sveltekit-replacestate, data-sveltekit-keepfocus, and data-sveltekit-noscroll attributes to control router behavior.
Form actions in +page.server.js
A +page.server.js file can export actions, which allow you to POST data to the server using the <form> element. Client-side JavaScript is optional; you can progressively enhance form interactions with JavaScript to provide the best user experience.
Default action in +page.server.js
A page can declare a default action by exporting an actions object with a default property. The default action receives an event object and is invoked when a form with method="POST" is submitted without specifying a named action.
Invoking default action from another page
To invoke a default action from a page other than where it is defined, add an action attribute to the form element pointing to the page, for example: <form method="POST" action="/login">.
Named actions in +page.server.js
A page can have multiple named actions by exporting an actions object with named properties. Instead of having a default action, you can define separate actions like login and register.
Invoking named actions
To invoke a named action, add a query parameter with the name prefixed by a forward slash character to the form's action attribute. For example: <form method="POST" action="?/register"> or <form method="POST" action="/login?/register">.
formaction attribute for multiple submit buttons
A button element can use the formaction attribute to POST the same form data to a different action than the parent form's action. For example: <button formaction="?/register">.
Cannot mix default and named actions
You cannot have default actions next to named actions in the same page, because posting to a named action without a redirect persists the query parameter in the URL, which would cause the next default POST to go through the named action from before.
Action receives RequestEvent
Each action receives a RequestEvent object, allowing you to read data with request.formData(). After processing, the action can return data that will be available through the form property on the page and through page.form app-wide until the next update.
Actions always use POST requests
Actions always use POST requests because GET requests should never have side-effects.
fail function for validation errors
The fail function, imported from '@sveltejs/kit', allows you to return an HTTP status code (typically 400 or 422 for validation errors) along with data. The status code is available through page.status and the data through form.
Action return data must be JSON serializable
The data returned from an action must be serializable as JSON. Beyond that, the structure is entirely up to you.
redirect function in actions
Actions can use the redirect function imported from '@sveltejs/kit' to redirect the user after processing. This works the same as in load functions.
Page load functions run after actions
After an action runs, the page will be re-rendered (unless a redirect or unexpected error occurs) with the action's return value available as the form prop. This means the page's load functions will run after the action completes.
Updating event.locals in actions
The handle hook runs before an action is invoked and does not rerun before load functions. If you use handle to populate event.locals based on a cookie, you must update event.locals when you set or delete the cookie in an action.
use:enhance directive for progressive enhancement
The use:enhance action from '$app/forms' progressively enhances a form by preventing full-page reloads. Without arguments, it emulates browser-native behavior but without the full-page reloads.
use:enhance requirements
use:enhance can only be used with forms that have method="POST" and point to actions defined in a +page.server.js file. It will not work with method="GET" (the default) or when posting to a +server.js endpoint.
use:enhance default behavior
Without arguments, use:enhance will update the form property and page.form/page.status on successful or invalid responses (but only if the action is on the same page being submitted from), reset the form element, invalidate all data on successful response, call goto on redirect, render the nearest +error boundary on error, and reset focus to the appropriate element.
Customizing use:enhance with SubmitFunction
You can provide a SubmitFunction to use:enhance that runs immediately before form submission. It receives formElement, formData, action, cancel, and submitter parameters. It can optionally return a callback that runs with the ActionResult object.
SubmitFunction callback parameters
The callback returned by SubmitFunction receives result (an ActionResult object) and update (a function to trigger default logic). The callback can also accept invalidateAll and reset parameters to update.
applyAction function
The applyAction function from '$app/forms' can be used to apply an ActionResult. For success and failure results, it sets page.status and updates form and page.form. For redirect results, it calls goto with invalidateAll. For error results, it renders the nearest +error boundary. Focus is reset in all cases.
Custom form submission with fetch
You can implement progressive enhancement yourself without use:enhance by adding an onsubmit handler to the form that prevents default behavior, creates a FormData object, fetches to the form action, deserializes the response using deserialize from '$app/forms', and applies the result.
deserialize function
The deserialize function from '$app/forms' must be used to deserialize action responses before processing them further. JSON.parse() is not sufficient because form actions can return Date or BigInt objects.
File input forms must use multipart/form-data in v2
In SvelteKit 2, forms containing file inputs must have enctype="multipart/form-data" attribute, otherwise non-JS submissions will omit the file. SvelteKit will throw an error if it encounters such a form during use:enhance submission to ensure forms work correctly without JavaScript.
form and data removed from use:enhance callbacks in v2
In SvelteKit 2, the form and data properties have been removed from use:enhance callbacks. Use formElement and formData instead, which were introduced as replacements in SvelteKit 1.
applyAction function signature and behavior
applyAction is a function imported from '$app/forms' that updates the form property of the current page with the given data and updates page.status. In case of an error, it redirects to the nearest error page. The function signature is: function applyAction<Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined>(result: import('@sveltejs/kit').ActionResult<Success, Failure>): Promise<void>;
deserialize function signature and usage
deserialize is a function imported from '$app/forms' that deserializes the response from a form submission. It takes a string parameter and returns an ActionResult. The function signature is: function deserialize<Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined>(result: string): import('@sveltejs/kit').ActionResult<Success, Failure>; It is typically used when manually fetching form responses to convert the response text into an ActionResult object.
enhance function signature and behavior
enhance is a function imported from '$app/forms' that enhances a <form> element to work with JavaScript. It takes an HTMLFormElement and an optional SubmitFunction callback, and returns an object with a destroy() method. The function signature is: function enhance<Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined>(form_element: HTMLFormElement, submit?: import('@sveltejs/kit').SubmitFunction<Success, Failure>): {destroy(): void;};
enhance submit function parameters
When using enhance with a custom submit function, the function receives the given FormData and the action that should be triggered. If cancel is called, the form will not be submitted. You can use the abort controller to cancel the submission in case another one starts.
enhance return value callback
If a function is returned from the submit callback in enhance, that function is called with the response from the server. If nothing is returned, the fallback will be used.
enhance default fallback behavior
When using enhance, if a custom function with a callback is not set, the default behavior includes: updating the form prop with the returned data if the action is on the same page as the form, updating page.status, resetting the <form> element and invalidating all data in case of successful submission with no redirect response, redirecting in case of a redirect response, and redirecting to the nearest error page in case of an unexpected error.
enhance update callback options
When providing a custom function with a callback in enhance and wanting to use the default behavior, invoke the update callback which accepts an options object with the following properties: reset (boolean, defaults to true) - if false, the form values will not be reset after successful submission; invalidateAll (boolean, defaults to true) - if false, the action will not call invalidateAll after submission.
Action type signature
Action is a form action method that is part of export const actions in +page.server.js. Type: Action<Params, OutputData, RouteId> = (event: RequestEvent<Params, RouteId>) => MaybePromise<OutputData>
ActionFailure interface
ActionFailure is an interface with properties: status (number), data (T), and a unique symbol. It is created by the fail() function.
ActionResult union type
ActionResult is returned when calling a form action via fetch. It is a union of four types: { type: 'success'; status: number; data?: Success }, { type: 'failure'; status: number; data?: Failure }, { type: 'redirect'; status: number; location: string }, or { type: 'error'; status?: number; error: any }
RemoteForm.method property
RemoteForm.method is always 'POST'.
RemoteForm.action property
RemoteForm.action is the URL string to send the form to.
RemoteForm.element property
RemoteForm.element gets the HTMLFormElement this form instance is currently attached to, if any.
RemoteForm.submit() method
RemoteForm.submit() submits the currently attached form programmatically. Returns Promise<boolean> with updates method accepting RemoteQueryUpdate array.
RemoteForm.enhance() method
RemoteForm.enhance() influences form submission. Accepts RemoteFormEnhanceCallback and returns object with method, action, and attachment symbol.
RemoteForm.for() method
RemoteForm.for() creates an instance of the form for a given id. The id is stringified for deduplication to reuse existing instances. Useful for multiple forms using same action in loops.
RemoteForm.preflight() method
RemoteForm.preflight() takes a StandardSchemaV1 schema and returns RemoteForm for chaining.
RemoteForm.validate() method
RemoteForm.validate() validates form contents programmatically. Takes optional options with includeUntouched (validate fields not yet touched) and preflightOnly (only run preflight validation). Returns Promise<void>.
RemoteForm.result property
RemoteForm.result gets the result of the form submission (type Output | undefined).
RemoteForm.pending property
RemoteForm.pending gets the number of pending submissions.
RemoteFormField.as() method
RemoteFormField.as() returns an object to spread onto input elements with correct type attribute, aria-invalid if invalid, and appropriate value/checked properties. Accepts input type like 'text', 'number', 'checkbox'.
InvalidField type for imperative validation
InvalidField is a function and proxy object for imperatively creating validation errors. Access properties to create field-specific issues (issue.fieldName('message')). The type structure mirrors input data structure for type-safe field access. Called with invalid(issue.foo(...), issue.nested.bar(...)).
SubmitFunction generic parameters and signature
SubmitFunction has generic parameters Success and Failure (both Record<string, unknown> | undefined, defaulting to Record<string, any>). Signature is (input: {action: URL, formData: FormData, formElement: HTMLFormElement, controller: AbortController, submitter: HTMLElement | null, cancel: () => void}) => MaybePromise<void | ((opts: {formData: FormData, formElement: HTMLFormElement, action: URL, result: ActionResult<Success, Failure>, update: (options?: {reset?: boolean, invalidateAll?: boolean}) => Promise<void>}) => MaybePromise<void>)>.
RemoteForm.submitted property
RemoteForm.submitted indicates whether the form has been submitted at least once (boolean).
RemoteForm.fields property
RemoteForm.fields allows accessing form fields using object notation with type RemoteFormFieldsRoot<Input>.
ValidationError interface
ValidationError interface (validation error thrown by invalid) has property: issues: StandardSchemaV1.Issue[] (the validation issues).
Actions type for form action exports
Actions is the type of export const actions in +page.server.js. It is defined as Record<string, Action<Params, OutputData, RouteId>>
fail() function creates ActionFailure objects
The fail() function creates an ActionFailure object for form submission failures. It accepts a status number and optional data. Signatures: fail(status: number): ActionFailure<undefined> or fail<T>(status: number, data: T): ActionFailure<T>
invalid() function for validation errors
The invalid() function throws a validation error to imperatively fail form validation. Available since 2.47.3. Can be used with issue passed to form actions to create field-specific issues. Signature: invalid(...issues: (StandardSchemaV1.Issue | string)[]): never
isActionFailure() checks for action failure
The isActionFailure() function checks whether a value is an ActionFailure thrown by fail(). Signature: isActionFailure(e: unknown): e is ActionFailure
isValidationError() checks for validation errors
The isValidationError() function checks whether a value is a validation error thrown by invalid(). Available since 2.47.3. Signature: isValidationError(e: unknown): e is ActionFailure