-
-
Notifications
You must be signed in to change notification settings - Fork 73
API reference
Throughout the reference, the following types are represented:
// T represents the validation schema z.object({ ... })
T extends AnyZodObject
// S refers to the underlying type of the schema, the actual data structure.
S = z.infer<T>// HTML input constraints returned from superValidate
export type InputConstraints = Partial<{
pattern: string;
min: number | string;
max: number | string;
required: boolean;
step: number;
minlength: number;
maxlength: number;
}>// The return value from superValidate
export type Validation<T> = {
valid: boolean;
data: S;
errors: Partial<
Record<keyof S, string[] | undefined>
>;
empty: boolean;
message: string | null;
constraints: Record<keyof S, InputConstraints>
};import {
superValidate,
setError,
noErrors,
actionResult
} from 'sveltekit-superforms/server';superValidate(
data:
| RequestEvent
| Request
| FormData
| Partial<S>
| null
| undefined,
schema: T,
options?: {
// See noErrors() reference
noErrors = false;
// See wiki entry for default entity values
implicitDefaults = true;
// Checks if Partial entities contains all required values
// (never checked if FormData exists)
checkMissingEntityFields = true;
}
): Promise<Validation<T>>If data is determined to be empty (null, undefined or no FormData), a validation result with a default entity for the schema is returned, in this shape:
{
valid: false;
errors: {};
data: S; // See further down for default entity values.
empty: true;
message: null;
constraints: Record<keyof S, InputConstraints>
}setError(
form: Validation<T>,
field: keyof S,
error: string | string[] | null,
options: { overwrite = false }
) : ActionFailure<{form: Validation<T>}>If you want to set an error on the form outside validation, use setError. It returns a fail(400, { form }) so it can be returned immediately, or more errors can be added by calling it multiple times before returning. Use the overwrite option to remove all previously set errors for the field.
If you want to return a form with no validation errors. Only the errors property will be modified, so valid still indicates the validation status. Useful for load functions where the entity is invalid, but as an initial state no errors should be displayed on the form.
noErrors(form: Validation<T>) : Validation<T>When not using form actions, this constructs an action result in a Response object, so you can return Validation<T> from your API/endpoints, for example in a login request:
src/routes/login/+server.ts
import { actionResult, superValidate } from '$lib/server';
import { z } from 'zod';
import type { RequestHandler } from './$types';
const loginSchema = z.object({
email: z.string().email(),
password: z.string().min(5)
});
export const POST = (async (event) => {
const form = await superValidate(event, loginSchema);
if (!form.valid) return actionResult('failure', { form });
// Verify login here //
return actionResult('success', { form });
}) satisfies RequestHandler;import {
superForm,
intProxy,
numberProxy,
booleanProxy,
dateProxy
} from 'sveltekit-superforms/client';superForm(
form: Validation<T> | null | undefined,
options?: FormOptions<T>
) : EnhancedForm<T>type FormOptions<T extends AnyZodObject> = {
applyAction?: boolean;
autoFocusOnError?: boolean | 'detect';
clearOnSubmit?: 'errors' | 'message' | 'errors-and-message' | 'none';
dataType?: 'form' | 'formdata' | 'json';
defaultValidator?: 'clear' | 'keep';
delayMs?: number;
errorSelector?: string;
invalidateAll?: boolean;
multipleSubmits?: 'prevent' | 'allow' | 'abort';
resetForm?: boolean;
scrollToError?: 'auto' | 'smooth' | 'off';
stickyNavbar?: string;
taintedMessage?: string | null | false;
timeoutMs?: number;
validators?: Validators<T>;
onSubmit?: (...params: Parameters<SubmitFunction>) => unknown | void;
async onResult?: (event: {
result: ActionResult;
update: async (
result: ActionResult<'success' | 'failure'>,
untaint?: boolean
);
formEl: HTMLFormElement;
cancel: () => void;
})
async onUpdate?: (event: {
form: Validation<T>;
cancel: () => void;
})
async onUpdated?: (event: {
form: Validation<T>;
})
async onError?:
| async (
result: ActionResult<'error'>,
message: Writable<string | null>
)
| 'set-message'
| 'apply'
| string;
flashMessage?: {
module: (import * as module from 'sveltekit-flash-message/client'),
onError?: (errorResult: ActionResult<'error'>) => App.PageData['flash']
};
};type EnhancedForm<T extends AnyZodObject> = {
form: Writable<Validation<T>['data']>;
errors: Writable<Validation<T>['errors']>;
constraints: Writable<Validation<T>['constraints']>;
message: Writable<string | null>;
valid: Readable<boolean>
empty: Readable<boolean>;
submitting: Readable<boolean>;
delayed: Readable<boolean>;
timeout: Readable<boolean>;
fields: Readable<FormField<T>[]>;
firstError: Readable<{ key: string; value: string } | null>;
allErrors: Readable<{ key: string; value: string }[]>;
tainted: Readable<boolean>;
enhance: (el: HTMLFormElement) => ReturnType<typeof formEnhance>;
reset: () => void;
async update: (
result: ActionResult<'success' | 'failure' | 'redirect'>,
untaint?: boolean
)
};Creates a proxy store for an integer form field. Changes in either the proxy store or the form field will reflect in the other.
Creates a proxy store for a numeric form field. Changes in either the proxy store or the form field will reflect in the other.
Creates a proxy store for a boolean form field. Changes in either the proxy store or the form field will reflect in the other. The option can be used to change what string value represents true.
dateProxy(form, fieldName, { format: 'date-local' | 'datetime-local' | 'time-local' | 'iso' = 'iso' )
Creates a proxy store for a boolean form field. Changes in either the proxy store or the form field will reflect in the other. The option can be used to format the string value differently, based on the input type for example.
Given the following schema:
const schema = z.object({
date: z.date()
})A proxy can be used like this:
<script lang="ts">
import { superForm, dateProxy } from 'sveltekit-superforms/client'
import type { PageData } from './$types';
export let data: PageData;
const form = superForm(data.form)
const date = dateProxy(form, 'date', { format: 'date-local' ))
</script>
<input name="date" type="date" bind:value={$date} />import SuperDebug from 'sveltekit-superforms/client/SuperDebug.svelte';SuperDebug gives you a colorized and formatted JSON output for any data structure, but usually $form.
<SuperDebug
data={any}
display?={true}
status?={true}
stringTruncate?={120}
ref?={HTMLPreElement}
/>