feat: allow to opt-out of use:enhance for forms

.changeset/spotty-queens-beam.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: allow opting out of `use:enhance` with `data-sveltekit-reload` on the form element or submit button

documentation/docs/20-core-concepts/30-form-actions.md

@@ -359,6 +359,8 @@ Without an argument, `use:enhance` will emulate the browser-native behaviour, ju
 - render the nearest `+error` boundary if an error occurs
 - [reset focus](accessibility#Focus-management) to the appropriate element
 
+You can add the [`data-sveltekit-reload`](link-options#data-sveltekit-reload) attribute on the `<form>` or the `<button>` to opt-out of this behavior and instead let the browser handle the form submission.
+
 ### Customising use:enhance
 
 To customise the behaviour, you can provide a `SubmitFunction` that runs immediately before the form is submitted, and (optionally) returns a callback that runs with the `ActionResult`. Note that if you return a callback, the default behavior mentioned above is not triggered. To get it back, call `update`.

documentation/docs/30-advanced/30-link-options.md

@@ -68,6 +68,8 @@ Occasionally, we need to tell SvelteKit not to handle a link, but allow the brow
 
 Links with a `rel="external"` attribute will receive the same treatment. In addition, they will be ignored during [prerendering](page-options#prerender).
 
+Forms with the `use:enhance` action can skip using the enhanced behavior by adding a `data-sveltekit-reload` attribute to the form element or the submit button.
+
 ## data-sveltekit-replacestate
 
 Sometimes you don't want navigation to create a new entry in the browser's session history. Adding a `data-sveltekit-replacestate` attribute to a link...

packages/kit/src/runtime/app/forms.js

@@ -2,6 +2,7 @@ import * as devalue from 'devalue';
 import { DEV } from 'esm-env';
 import { invalidateAll } from './navigation.js';
 import { app, applyAction } from '../client/client.js';
+import { link_option } from '../client/utils.js';
 
 export { applyAction };
 
@@ -117,6 +118,16 @@ export function enhance(form_element, submit = () => {}) {
 			: clone(form_element).method;
 		if (method !== 'post') return;
 
+		/** @type {import('../client/utils.js').ValidLinkOptions<'reload'> | null} */
+		let reload = null;
+		if (event.submitter) {
+			reload = link_option(event.submitter, 'reload');
+		}
+		if (reload === null) {
+			reload = link_option(form_element, 'reload');
+		}
+		if (reload === '' || reload === 'true') return;
+
 		event.preventDefault();
 
 		const action = new URL(

packages/kit/src/runtime/client/utils.js

@@ -52,7 +52,7 @@ const valid_link_options = /** @type {const} */ ({
  * @param {Element} element
  * @param {T} name
  */
-function link_option(element, name) {
+export function link_option(element, name) {
 	const value = /** @type {ValidLinkOptions<T> | null} */ (
 		element.getAttribute(`data-sveltekit-${name}`)
 	);