API reference - lnfel/sveltekit-superforms GitHub Wiki

Types

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: Partial<
    Record<keyof S, InputConstraints>
  >
};

Server API

import {
  superValidate,
  setError,
  noErrors,
  actionResult
} from 'sveltekit-superforms/server';

superValidate(data, schema, options?)

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;
    // Add metadata to the validation entity:
    includeMeta = false;
    // Checks if partial entities contains all required values (not checked for FormData)
    checkMissingEntityFields = true;
    // Form id, for multiple forms support:
    id?: string
  }
): 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: Partial<
    Record<keyof S, InputConstraints>
  >
}

setError(form, field, error, options?)

setError(
  form: Validation<T>,
  field: keyof S,
  error: string | string[] | null,
  options?: { overwrite = false, status = 400 }
) : ActionFailure<{form: Validation<T>}>

If you want to set an error on the form outside validation, use setError. It returns a fail(status, { 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, and status to set a different status than the default 400.

noErrors(form)

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. Can be 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>

actionResult(type, data?, status?)

When using endpoints instead of form actions, you must return an ActionResult, throw redirect(...) won't work directly since superForms expects an ActionResult. This method helps you construct one in a Response object, so you can return a validation object from your API/endpoints.

// Every call can take a http status as a third parameter.
actionResult('success', { form })
actionResult('failure', { form })
actionResult('redirect', '/')
actionResult('error', 'Error message')

Example for 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;

Client API

import {
  superForm,
  intProxy,
  numberProxy,
  booleanProxy,
  dateProxy
} from 'sveltekit-superforms/client';

superForm(form, options?)

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
  )
};

intProxy(form, fieldName)

Creates a proxy store for an integer form field. Changes in either the proxy store or the form field will reflect in the other.

numberProxy(form, fieldName)

Creates a proxy store for a numeric form field. Changes in either the proxy store or the form field will reflect in the other.

booleanProxy(form, fieldName, { trueStringValue = 'true' })

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.

Proxy 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} />

Components

import SuperDebug from 'sveltekit-superforms/client/SuperDebug.svelte';

SuperDebug

SuperDebug gives you a colorized and formatted JSON output for any data structure, but usually $form.

<SuperDebug
  data={any}
  display?={true}
  label?={""}
  promise?={false}
  status?={true}
  stringTruncate?={120}
  ref?={HTMLPreElement}
/>

SuperDebug props

Prop Type Default value Description
data any undefined Data to be displayed by SuperDebug
display Boolean true Whether to show or hide SuperDebug
label String "" Add useful label to SuperDebug, useful when using multiple instances of SuperDebug in a page
promise Boolean false When true, SuperDebug uses svelte's await block to load the data. Data is assumed to be async but can also load non-async data using await block!
status Boolean true Whether to show or hide status code.
stringTruncate Number 120 Truncate long string in output.
ref HTMLPreElement undefined Binds pre tag to ref.

SuperDebug usage

Please see the +page.svelte file in src/routes/super-debug on common usage of SuperDebug.

https://github.com/ciscoheat/sveltekit-superforms/tree/main/src/routes/super-debug

⚠️ **GitHub.com Fallback** ⚠️