createEnhancedForm API Reference
Relevant source files
The following files were used as context for generating this wiki page:The createEnhancedForm function is a helper utility provided by the @opensky/remotes package. It is designed to augment SvelteKit's native remote form functions by introducing tracked state, semantic callbacks for various stages of the request lifecycle, and optional integration with the createValidation helper. This allows for more robust and user-friendly form handling, including features like delayed/timeout states and optimistic updates, with less boilerplate code.
The function is exported from the package's main entry point. It creates a reactive state machine for a given RemoteForm instance, enabling developers to easily build UIs that respond to the form's submission status.
Sources: packages/remotes/README.md, packages/remotes/src/lib/index.ts:2, packages/remotes/src/lib/enhance.svelte.ts:213
Initialization
To use the helper, you import createEnhancedForm and call it with a SvelteKit RemoteForm instance and an optional configuration object.
import { createEnhancedForm } from '@opensky/remotes';
import { myForm } from './myForm.remote';
// With validation and timing options
const valid = createValidation(myForm);
const form = createEnhancedForm(myForm, {
validation: valid,
delayMs: 500,
timeoutMs: 3500
});
Sources: packages/remotes/README.md
Parameters
The createEnhancedForm function accepts two arguments:
remote: TheRemoteFormobject created by SvelteKit'screateRemote.options: An optional configuration object.
The options object can contain the following properties:
| Option | Type | Description |
|---|---|---|
validation | Validation | An optional instance returned from createValidation for automatic validation handling during the form lifecycle. |
delayMs | number | Milliseconds to wait before the form state transitions to 'delayed'. If provided, the delayed state and onDelay callback become available. |
timeoutMs | number | Milliseconds to wait before the form state transitions to 'timeout'. If provided, the timeout state and onTimeout callback become available. |
The function is overloaded to provide type-safe return values. The presence of delayMs and timeoutMs in the options conditionally adds delayed and timeout properties to the returned object and enables the corresponding onDelay and onTimeout callbacks.
Sources: packages/remotes/src/lib/enhance.svelte.ts:55-66, packages/remotes/src/lib/enhance.svelte.ts:213-241, packages/remotes/CHANGELOG.md:12-14
Returned Object
The createEnhancedForm function returns an object containing state getters and methods to manage the form enhancement.
| Property/Method | Type | Description |
|---|---|---|
enhance() | function | The form enhancement handler to be passed to SvelteKit's form.enhance(). |
reset() | function | A method to manually reset the form's state back to 'idle'. |
state | string | A reactive $state variable holding the current form state string (e.g., 'idle', 'pending'). |
idle | boolean | A boolean getter that is true when state is 'idle'. |
pending | boolean | A boolean getter that is true when state is 'pending'. |
issues | boolean | A boolean getter that is true when state is 'issues'. |
error | boolean | A boolean getter that is true when state is 'error'. |
result | boolean | A boolean getter that is true when state is 'result'. |
delayed | boolean | Conditional. A boolean getter that is true when state is 'delayed'. Only available if delayMs was provided at creation. |
timeout | boolean | Conditional. A boolean getter that is true when state is 'timeout'. Only available if timeoutMs was provided at creation. |
Sources: packages/remotes/README.md, packages/remotes/src/lib/enhance.svelte.ts:143-210, packages/remotes/CHANGELOG.md:4
Form State Management
The core of createEnhancedForm is a state machine that tracks the form submission lifecycle. The state property transitions through several stages based on the submission process.
The diagram below illustrates the possible state transitions.
This diagram shows the flow of the form state from idle through various submission states and back.
States
idle: The initial and final state. The form is not in the process of being submitted.pending: The state immediately after submission begins, before any delay or timeout.delayed: An optional state entered if the submission takes longer thandelayMs. Useful for showing a loading indicator only for longer requests.timeout: An optional state entered if the submission takes longer thantimeoutMs. Useful for showing a timeout message.issues: The state when the server returns validation issues without an error or result.error: The state when the submission promise rejects or an error is thrown.result: The state when the submission is successful and returns a result. The form element is also reset.
Sources: packages/remotes/src/lib/enhance.svelte.ts:38, packages/remotes/src/lib/enhance.svelte.ts:252-344
The enhance Handler
The returned enhance method is the primary interface for using the created form helper. It wraps SvelteKit's enhance callback, providing a structured way to handle the submission lifecycle with semantic callbacks.
The sequence diagram below shows the internal logic of the enhance handler.
Callbacks
The second argument to the enhance handler is a callbacks object.
| Callback | Context | Description |
|---|---|---|
onSubmit | { cancel, updates, data, ... } | Called when submission begins. Use cancel() to halt submission (e.g., for client-side validation). Use updates() to provide optimistic update queries. |
onDelay | { data, form, remote } | Conditional. Called when the delayed state is reached. Only allowed if delayMs was set at creation. |
onTimeout | { data, form, remote } | Conditional. Called when the timeout state is reached. Only allowed if timeoutMs was set at creation. |
onReturn | { result, data, ... } | Called when the submission returns a successful result. |
onIssues | { data, form, remote } | Called when the submission returns with validation issues. |
onError | { error, data, ... } | Called when the submission encounters an error. |
Sources: packages/remotes/README.md, packages/remotes/src/lib/enhance.svelte.ts:93-141
onSubmit Context
The onSubmit callback receives a special context object with two important functions:
cancel(state?: 'error' | 'issues'): Immediately stops the form submission. You can optionally set the final state to'error'or'issues'. If no state is provided, it defaults to'idle'.updates(...queries): Accepts SvelteKit remote query overrides for performing optimistic UI updates.
Sources: packages/remotes/src/lib/enhance.svelte.ts:81-87, packages/remotes/CHANGELOG.md:5
Integration with createValidation
When a validation instance from createValidation is passed during initialization, createEnhancedForm automatically calls its methods at appropriate lifecycle stages:
validation.updateIssues(): This is called automatically when the form submission returns validation issues (theonIssuesflow). This populates the validation helper with the latest issues from the server.validation.validateAll(): This is called automatically when the form submission results in an error (theonErrorflow).
This integration automates the process of synchronizing validation state between the form and the server response.
Sources: packages/remotes/src/lib/enhance.svelte.ts:57, packages/remotes/src/lib/enhance.svelte.ts:331-332, packages/remotes/src/lib/enhance.svelte.ts:341-342, packages/remotes/src/lib/validation.svelte.ts:85, packages/remotes/src/lib/validation.svelte.ts:94
Conclusion
createEnhancedForm is a powerful utility that significantly enhances SvelteKit's remote forms. By providing a structured state machine, semantic lifecycle callbacks, and seamless integration with createValidation, it simplifies the management of complex form interactions. Features like conditional timed states (delayed, timeout) and hooks for client-side cancellation and optimistic updates (onSubmit) empower developers to build more responsive and intuitive user interfaces with less effort.