Superforms

https://superforms.rocks
Admin
Superforms is a SvelteKit form library that provides a comprehensive solution for server and client...
Tokens:88,394
Snippets:635
Trust Score:8.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and run development server with npm or pnpm

Source: https://superforms.rocks/contributing

Install dependencies and start the development server. The first block uses npm, the second uses pnpm as an alternative package manager.

```bash
npm install
npm run dev
```

```bash
pnpm install
pnpm dev
```

--------------------------------

### Install Superforms with Joi adapter

Source: https://superforms.rocks/get-started/class-validator

Install the Superforms package and the Joi adapter as dev dependencies.

```bash
npm i -D sveltekit-superforms joi
```

--------------------------------

### Install Superforms with npm

Source: https://superforms.rocks/get-started/arktype

Install the sveltekit-superforms package as a dev dependency using npm. Run this in your project folder.

```bash
npm i -D sveltekit-superforms zod
```

--------------------------------

### Install Superforms and Arktype

Source: https://superforms.rocks/get-started/%40vinejs/vine

Install the required packages for using Superforms with Arktype in a SvelteKit project.

```bash
npm i -D sveltekit-superforms arktype
```

--------------------------------

### Install sveltekit-superforms and @exodus/schemasafe

Source: https://superforms.rocks/get-started

Install the Superforms package and the @exodus/schemasafe adapter for JSON Schema validation. Run this in your project folder after selecting your environment (npm, pnpm, or yarn).

```bash
npm i -D sveltekit-superforms @exodus/schemasafe
```

--------------------------------

### Timer state transitions for interactive example

Source: https://superforms.rocks/concepts/timers

Timer state transitions for the interactive example with delayMs set to 500 ms and timeoutMs set to 2000 ms. The default multipleSubmits setting prevents the form from being submitted multiple times until the timeout state is reached.

```text
Idle → submitting → delayed → timeout
       0 ms         500 ms    2000 ms
```

--------------------------------

### intProxy with empty and initiallyEmptyIfZero options

Source: https://superforms.rocks/whats-new-v2

Configure number fields to show 0 when empty and start empty using the 'zero' empty option and initiallyEmptyIfZero.

```typescript
const schema = z.object({
  num: z.number()
})

const proxy = intProxy(form, 'num', { empty: 'zero', initiallyEmptyIfZero: true })
```

--------------------------------

### Recreating tags example with TextField

Source: https://superforms.rocks/components

Recreates the tags example using the `TextField` component. It iterates over `$form.tags` and renders a `TextField` for each tag's name, using the `field` prop with an index expression.

```svelte
<form method="POST" use:enhance>
  <TextField name="name" {superform} field="name" />

  <h4>Tags</h4>

  {#each $form.tags as _, i}
    <TextField name="tags" {superform} field="tags[{i}].name" />
  {/each}
</form>
```

--------------------------------

### defaultValues example

Source: https://superforms.rocks/api

Returns the default values for a schema, either Superforms defaults or those set on the schema. The example shows a Zod schema with a default array value, and the resulting defaults object.

```typescript
import { defaultValues } from 'sveltekit-superforms';
import { zod } from 'sveltekit-superforms/adapters';
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(2),
  tags: z.string().min(1).array().default(['a', 'b'])
});

// Returns { name: '', tags: ['a', 'b'] }
const defaults = defaultValues(zod(schema));
```

--------------------------------

### Login request example with endpoint and form

Source: https://superforms.rocks/api

Complete login request example: a +server.ts endpoint that validates a login form and returns an ActionResult, paired with the HTML form that points to the endpoint and uses use:enhance. The endpoint returns failure if invalid, otherwise sets a success message and returns success.

```typescript
import { actionResult, superValidate, setMessage } from 'sveltekit-superforms';
import { zod } from 'sveltekit-superforms/adapters';
import { z } from 'zod';

const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(5)
});

export const POST = async ({ request }) => {
  const form = await superValidate(request, zod(loginSchema));
  if (!form.valid) return actionResult('failure', { form });

  // TODO: Verify login here //

  setMessage(form, 'Login successful!');
  return actionResult('success', { form });
};
```

```html
<form method="POST" action="/login" use:enhance>
  <!-- Business as usual -->
```

--------------------------------

### Load data in +page.ts for SPA

Source: https://superforms.rocks/concepts/spa

Load initial data for a SPA page using +page.ts instead of +page.server.ts. This example fetches user data from an external API based on a route parameter, validates it with Zod, and returns the form for Superforms.

```typescript
import { error } from '@sveltejs/kit';
import { superValidate } from 'sveltekit-superforms';
import { zod } from 'sveltekit-superforms/adapters';
import { z } from 'zod';

export const _userSchema = z.object({
  id: z.number().int().positive(),
  name: z.string().min(2),
  email: z.string().email()
});

export const load = async ({ params, fetch }) => {
  const id = parseInt(params.id);

  const request = await fetch(
    `https://jsonplaceholder.typicode.com/users/${id}`
  );
  if (request.status >= 400) throw error(request.status);

  const userData = await request.json();
  const form = await superValidate(userData, zod(_userSchema));

  return { form };
};
```

--------------------------------

### Use dateProxy for HTML date field

Source: https://superforms.rocks/api

Example of using dateProxy to create a proxy for a date field, bound to an HTML date input. Requires sveltekit-superforms and svelte. The proxy is created with format 'date' and empty 'undefined'.

```svelte
<script lang="ts">
  import { superForm, dateProxy } from 'sveltekit-superforms';
  import type { PageData } from './$types.js';
  import { untrack } from 'svelte';

  let { data } = $props();

  const { form, enhance } = superForm(untrack(() => data.form));
  const date = dateProxy(form, 'date', { format: 'date', empty: 'undefined' });
</script>

<input name="date" type="date" bind:value={$date} />
```

--------------------------------

### Formsnap form example with Field, Control, Label, Description, and FieldErrors

Source: https://superforms.rocks/formsnap

Use this snippet to create an accessible form with Formsnap. It uses the Field, Control, Label, Description, and FieldErrors components. The form uses the `use:enhance` action and binds form data with `$formData`. Each field includes a description and error display.

```svelte
<form method="POST" use:enhance>
  <Field {form} name="name">
    <Control let:attrs>
      <Label>Name</Label>
      <input {...attrs} bind:value={$formData.name} />
    </Control>
    <Description>Be sure to use your real name.</Description>
    <FieldErrors />
  </Field>
  <Field {form} name="email">
    <Control let:attrs>
      <Label>Email</Label>
      <input {...attrs} type="email" bind:value={$formData.email} />
    </Control>
    <Description>It's preferred that you use your company email.</Description>
    <FieldErrors />
  </Field>
  <Field {form} name="password">
    <Control let:attrs>
      <Label>Password</Label>
      <input {...attrs} type="password" bind:value={$formData.password} />
    </Control>
    <Description>Ensure the password is at least 10 characters.</Description>
    <FieldErrors />
  </Field>
</form>
```

--------------------------------

### Create a new SvelteKit project

Source: https://superforms.rocks/get-started/arktype

Create a new SvelteKit project from scratch using the sv create command.

```bash
npx sv create my-app
```

--------------------------------

### Use defaults with schema for default values

Source: https://superforms.rocks/migration-v2

Replace superValidateSync with defaults when only getting default values from the schema. This example shows using defaults with a schema and SPA mode.

```typescript
import { defaults } from 'sveltekit-superforms'

// Getting the default values from the schema:
const { form, errors, enhance } = superForm(defaults(zod(schema)), {
  SPA: true,
  validators: zod(schema),
  // ...
})
```

--------------------------------

### Nested<T, string[]> example

Source: https://superforms.rocks/api

Shows the Nested<T, R> type, which replaces all primitive values of T with R and removes optional modifiers. In this example, R is string[].

```typescript
type Nested<T, string[]> = {
  name: string[],
  email: string[]
};
```

--------------------------------

### Create SvelteKit project with npx or pnpx

Source: https://superforms.rocks/crud

Create a new SvelteKit project named sf-crud. Choose Skeleton project and TypeScript syntax at the prompts.

```bash
npx sv create sf-crud
```

```bash
pnpx sv create sf-crud
```

--------------------------------

### superForm(form, options?)

Source: https://superforms.rocks/api

Documentation for the superForm function, the main entry point for creating a SuperForm instance.

```APIDOC
## superForm(form, options?)

### Description
Creates a SuperForm instance for a SvelteKit form, providing reactive form state, validation, and event handling.

### Method
superForm

### Signature
```typescript
superForm<T, M = any>(
  form: SuperValidated<T, M, In> | null | undefined,
  options?: FormOptions<T, M, In>
) : SuperForm<T, M>
```

### Parameters
#### form
- **form** (SuperValidated<T, M, In> | null | undefined) - Required - The validated form data from the server.

#### options
- **options** (FormOptions<T, M, In>) - Optional - Configuration options for the form.

### Options
#### Basics
- **id** (string) - Optional - Unique identifier for the form.
- **applyAction** (boolean) - Optional - Whether to apply the server action result.
- **invalidateAll** (boolean | 'force') - Optional - Whether to invalidate all data on submission.
- **resetForm** (boolean | (() => boolean)) - Optional - Whether to reset the form after submission.
- **taintedMessage** (boolean | string | (() => Promise<boolean>)) - Optional - Message to show when the form is tainted.
- **dataType** ('form' | 'json') - Optional - The data format for submission.
- **multipleSubmits** ('prevent' | 'allow' | 'abort') - Optional - How to handle multiple submissions.
- **SPA** (true) - Optional - Enable SPA mode.

#### Error handling
- **scrollToError** ('auto' | 'smooth' | 'off' | boolean | ScrollIntoViewOptions) - Optional - Scroll behavior on error.
- **autoFocusOnError** ('detect' | boolean) - Optional - Whether to auto-focus on error.
- **errorSelector** (string) - Optional - CSS selector for error elements.
- **selectErrorText** (boolean) - Optional - Whether to select error text.
- **stickyNavbar** (string) - Optional - Selector for sticky navbar to offset scroll.

#### Events
- **onSubmit** (function) - Optional - Called before submission. See SubmitFunction for details.
- **onResult** (function) - Optional - Called after the server returns a result.
- **onUpdate** (function) - Optional - Called when the form is updated with new data.
- **onUpdated** (function) - Optional - Called after the form has been updated.
- **onChange** (function) - Optional - Called when the form changes.
- **onError** ('apply' | function) - Optional - Called when an error occurs.

#### Client-side validation
- **validators** (ClientValidationAdapter | ValidationAdapter | false | 'clear') - Optional - Client-side validators.
- **validationMethod** ('auto' | 'oninput' | 'onblur' | 'onsubmit') - Optional - When to run validation.
- **clearOnSubmit** ('errors-and-message' | 'message' | 'errors' | 'none') - Optional - What to clear on submit.
- **delayMs** (number) - Optional - Delay before validation.
- **timeoutMs** (number) - Optional - Timeout for validation.

#### Other
- **transport** (Transport) - Optional - For handling arbitrary types in the form.
- **warnings** ({ duplicateId?: boolean }) - Optional - Disable warnings.

### Returns
- **SuperForm<T, M>** - The SuperForm instance.

### Example
```typescript
import { superForm } from 'sveltekit-superforms';

const { form, errors, enhance } = superForm(data.form, {
  validators: false,
  resetForm: true,
});
```
```

--------------------------------

### onError event example

Source: https://superforms.rocks/concepts/events

Use onError to catch errors from the SvelteKit error function. The result.error shape varies by error type; this example sets the message store to the error message or a fallback.

```javascript
const { form, enhance, message } = superForm(data.form, {
  onError({ result }) {
    $message = result.error.message || "Unknown error";
  }
});
```

--------------------------------

### message usage example

Source: https://superforms.rocks/api

Example of using message in a SvelteKit form action. When the form is invalid, message returns fail(400, { form }); when status is >= 400, it returns fail and sets form.valid to false; otherwise it returns { form }.

```typescript
import { message, superValidate } from 'sveltekit-superforms/server';

export const actions = {
  default: async (event) => {
    const form = await superValidate<typeof schema, string>(event, schema);

    if (!form.valid) {
      // Will return fail(400, { form }) since form isn't valid
      return message(form, 'Invalid form');
    }

    if (form.data.email.includes('spam')) {
      // Will return fail and set form.valid = false, since status is >= 400
      return message(form, 'No spam please', {
        status: 403
      });
    }

    // Returns { form }
    return message(form, 'Valid form!');
  }
};
```

--------------------------------

### Create an intProxy from form or superForm

Source: https://superforms.rocks/concepts/proxy-objects

Shows how to create an intProxy from the form store or the whole superForm object. Passing the whole superForm allows setting a tainted option (e.g., { taint: false }) to prevent tainting the form when the proxy updates.

```javascript
import { superForm, intProxy } from 'sveltekit-superforms';

// Assume the following schema:
// { id: number }

const superform = superForm(data.form);
const { form, errors, enhance } = superform;

// Returns a Writable<string>
const idProxy = intProxy(form, 'id');

// Use the whole superForm object to prevent tainting
const idProxy2 = intProxy(superform, 'id', { taint: false });
```

--------------------------------

### Add normalize.css and sakura.css to app.html

Source: https://superforms.rocks/crud

Add these stylesheet links to the <head> of src/app.html for a nicer visual experience.

```html
<link rel="stylesheet" href="https://unpkg.com/normalize.css@8.0.1/normalize.css" />
<link rel="stylesheet" href="https://unpkg.com/sakura.css/css/sakura.css" />
```

--------------------------------

### Use withFiles helper for file uploads

Source: https://superforms.rocks/concepts/files

Demonstrates the `withFiles` helper required when using SvelteKit's default `fail` or returning the form directly. It removes file objects from the form data so SvelteKit can serialize it properly.

```javascript
// Importing the default fail:
import { fail } from '@sveltejs/kit';
// Prefer to import message, setError and fail from here instead:
import { withFiles } from 'sveltekit-superforms';

// With the @sveltejs/kit fail:
if (!form.valid) {
  return fail(400, withFiles({ form }));
}

// When returning just the form
return withFiles({ form })
```

--------------------------------

### Return message object from form action

Source: https://superforms.rocks/concepts/messages

Return a message object from a form action to be used programmatically, for example in a toast notification.

```typescript
return message(form, { status: 'success', text: 'All went well' });
```

--------------------------------

### intProxy usage and options

Source: https://superforms.rocks/api

Creates a string store for an integer field. The 'empty' option sets the field to 'null', 'undefined', or 'zero'; 'initiallyEmptyIfZero' sets the field to empty when the initial value is zero, usually combined with empty: 'zero'.

```typescript
import { superForm, intProxy } from 'sveltekit-superforms';
import { untrack } from 'svelte';
let { data } = $props();

const { form } = superForm(untrack(() => data.form));
const proxy = intProxy(form, 'field', { options });
```

```typescript
{ 
  empty?: 'null' | 'undefined' | 'zero';
  initiallyEmptyIfZero?: boolean;
  taint?: boolean | 'untaint' | 'untaint-form';
}
```

--------------------------------

### Import proxy functions from sveltekit-superforms

Source: https://superforms.rocks/api

Import all proxy functions from 'sveltekit-superforms'. The primitives (booleanProxy, dateProxy, intProxy, numberProxy, stringProxy) return a Writable<string>, while file proxies and field proxies have types depending on the field.

```typescript
import {
  // The primitives return a Writable<string>:
  booleanProxy,
  dateProxy,
  intProxy,
  numberProxy,
  stringProxy,
  // File proxies
  fileProxy,
  fileFieldProxy, // formFieldProxy
  // File[] proxies
  filesProxy,
  filesFieldProxy, // arrayProxy
  // The type of the others depends on the field:
  formFieldProxy,
  arrayProxy,
  fieldProxy      
} from 'sveltekit-superforms';
```

--------------------------------

### Define schema with optional date field

Source: https://superforms.rocks/api

Schema definition using Zod with an optional date field, used as the basis for the proxy example.

```typescript
const schema = z.object({
  date: z.date().optional()
});
```

--------------------------------

### Return files in form actions with Superforms helpers

Source: https://superforms.rocks/concepts/files

Shows how to return forms with file objects using Superforms' `fail`, `message`, and `setError` helpers, which handle file serialization automatically. This is the recommended approach because file objects cannot be serialized by SvelteKit.

```javascript
import { message, setError, fail } from 'sveltekit-superforms';

// message, setError and the Superforms fail handles this automatically:
if (!form.valid) return fail(400, { form });
return message(form, 'Posted OK!');
return setError(form, 'image', 'Could not process file.');
```

--------------------------------

### Creating a ValidationAdapter with zod

Source: https://superforms.rocks/api

Shows how to create a ValidationAdapter using the zod adapter. The adapter type is inferred from the schema, and the comment explains the resulting type.

```typescript
import type { Infer, InferIn } from 'sveltekit-superforms';
import { zod, zodClient } from 'sveltekit-superforms/adapters';
import { z } from 'zod';

const schema = z.object({
  name: z.string().min(3)
})

// Type is now ValidationAdapter<Infer<typeof schema>, InferIn<typeof schema>>
// Which is the same as ValidationAdapter<{name: string}, {name: string}>
const adapter = zod(schema);
```

--------------------------------

### onUpdated event example

Source: https://superforms.rocks/concepts/events

Use onUpdated to run code after form validation, such as showing a toast notification. The form parameter contains the validation result and should be treated as read-only.

```javascript
const { form, enhance } = superForm(data.form, {
  onUpdated({ form }) {
    if (form.valid) {
      // Successful post! Do some more client-side stuff,
      // like showing a toast notification.
      toast(form.message, { icon: '✅' });
    }
  }
});
```

--------------------------------

### Add styling for users list and form

Source: https://superforms.rocks/crud

Styling for the page, including classes for invalid, danger, delay, and the users list layout. Add this at the end of the file.

```css
<style>
  .invalid {
    color: red;
  }

  .danger {
    background-color: brown;
  }

  .delay {
    background-color: lightblue;
  }

  form {
    display: flex;
    flex-direction: column;
    gap: 1em;
    align-items: flex-start;
    margin-bottom: 2em;
  }

  hr {
    width: 100%;
    margin-block: 2em;
  }

  .users {
    columns: 3 150px;
  }

  .users > * {
    display: block;
    white-space: nowrap;
    overflow-x: hidden;
  }
</style>
```

--------------------------------

### Appending a new tag to $form.tags

Source: https://superforms.rocks/components

Appends a new tag object to the `tags` array in the `$form` store. This is used to add new tags dynamically in the tags example.

```javascript
$form.tags = [...$form.tags, { id: undefined, name: '' }];
```

--------------------------------

### Server API imports

Source: https://superforms.rocks/api

Imports the main server API functions from sveltekit-superforms.

```typescript
import {
  superValidate,
  actionResult,
  defaultValues,
  message,
  setError,
  fail,
  withFiles
} from 'sveltekit-superforms';
```

--------------------------------

### Usage of generic TextField component

Source: https://superforms.rocks/components

Shows the desired usage of a generic TextField component that receives the superform and a field name. This is the motivating example for the typesafe generic component.

```svelte
<TextField {superform} field="name" />
```

--------------------------------

### intProxy(form, fieldName, options?)

Source: https://superforms.rocks/api

Creates a string store for an integer field in the schema. It's rarely needed as Svelte handles this automatically with bind:value.

```APIDOC
## [PROXY] intProxy(form, fieldName, options?)

### Description
Creates a string store for an **integer** field in the schema. It's rarely needed as Svelte handles this automatically with `bind:value`.

### Method
PROXY

### Endpoint
intProxy(form, fieldName, options?)

### Parameters
#### Parameters
- **form** (SuperForm) - Required - The form object from superForm.
- **fieldName** (string) - Required - The name of the field in the schema.
- **options** (object) - Optional - Configuration options.

#### Options
- **empty** ('null' | 'undefined' | 'zero') - Optional - Set the field to some of the defined values.
- **initiallyEmptyIfZero** (boolean) - Optional - Set the field to empty if the initial value is zero, to show the placeholder text, usually in combination with the `empty` option being set to `'zero'`.
- **taint** (boolean | 'untaint' | 'untaint-form') - Optional - Control tainting behavior.

### Request Example
```typescript
import { superForm, intProxy } from 'sveltekit-superforms';
import { untrack } from 'svelte';
let { data } = $props();

const { form } = superForm(untrack(() => data.form));
const proxy = intProxy(form, 'field', { options });
```

### Response
#### Success Response (200)
- **proxy** (Writable<string>) - A writable string store that syncs with the form field.

#### Response Example
```typescript
// The proxy is a writable store that can be used in the view.
```
```

--------------------------------

### Proxy output with date set to undefined

Source: https://superforms.rocks/concepts/proxy-objects

Example output showing the date field set to undefined when an invalid date is entered, using the empty option of the proxy.

```json
{
  date: undefined
}
```

--------------------------------

### Configure loading timers with delayMs and timeoutMs

Source: https://superforms.rocks/concepts/timers

Initialize the superForm with delayMs and timeoutMs options. delayMs should be positive and always smaller than or equal to timeoutMs, otherwise the timer behavior will be undefined. The use:enhance action must be added to the form element for this client-side behavior to work.

```javascript
const { form, enhance, submitting, delayed, timeout } = superForm(data.form, {
  delayMs?: 500
  timeoutMs?: 8000
})
```

--------------------------------

### Validation object returned from superValidate

Source: https://superforms.rocks/get-started/arktype

Example validation object returned from superValidate after posting an invalid form. Shows the structure with id, valid, posted, data, and errors properties.

```json
{
  id: 'a3g9kke',
  valid: false,
  posted: true,
  data: { name: 'Hello world!', email: '' },
  errors: { email: [ 'Invalid email' ] }
}
```

--------------------------------

### defaults

Source: https://superforms.rocks/api

Documentation for the defaults export, which provides default configuration values.

```APIDOC
## defaults

### Description
Provides default values for form options and utilities.

### Method
defaults

### Usage
```typescript
import { defaults } from 'sveltekit-superforms';
```

### Details
- The `defaults` export provides default configuration values for SuperForm options.
- It can be used to access default settings or to reset options to their defaults.
```

--------------------------------

### SuperDebug output showing default form values

Source: https://superforms.rocks/get-started/arktype

Example output shown by `SuperDebug` when the form is populated with default values from the schema. The data updates automatically when editing form fields.

```json
{
  name: "Hello world!",
  email: ""
}
```

--------------------------------

### Import proxy functions from sveltekit-superforms

Source: https://superforms.rocks/concepts/proxy-objects

Imports all proxy functions from sveltekit-superforms. The primitives (booleanProxy, dateProxy, intProxy, numberProxy, stringProxy) return a Writable<string>, while the type of formFieldProxy, arrayProxy, and fieldProxy depends on the field.

```javascript
import {
  // The primitives return a Writable<string>:
  booleanProxy,
  dateProxy,
  intProxy,
  numberProxy,
  stringProxy,
  // The type of the other three depends on the field:
  formFieldProxy,
  arrayProxy,
  fieldProxy      
} from 'sveltekit-superforms';
```

--------------------------------

### superValidate with data and errors option

Source: https://superforms.rocks/concepts/error-handling

Shows how superValidate behaves when data is posted or populated. Errors are returned unless the errors option is set to false. Includes both load and action examples.

```javascript
export const load = async () => {
  const initialData = { test: 123 };

  // Form is populated, so errors will be set if validation fails
  const form = await superValidate(initialData, zod(schema));

  // No errors will be set, even if validation fails
  const form2 = await superValidate(initialData, zod(schema), { errors: false });
};

export const actions = {
  default: async ({ request }) => {
    // Data is posted, so form.errors will be populated
    const form = await superValidate(request, zod(schema));

    // Unless we turn them off (which is rare in form actions)
    const form2 = await superValidate(request, zod(schema), { errors: false });
  }
};
```

--------------------------------

### validators: change client-side validators

Source: https://superforms.rocks/concepts/events

Changes client-side validators for the current submission using the validators function. In this example, it applies a Zod schema on the first step and disables validation on the last step.

```javascript
import { superForm } from 'sveltekit-superforms';
import { zod } from 'sveltekit-superforms/adapters';
import { customSchema } from './schemas.js';

let step = $state(1);
const lastStep = 5;

const { form, enhance } = superForm(data.form, {
  onSubmit({ validators }) {
    if(step == 1) validators(zod(customSchema));
    else if(step == lastStep) validators(false);
  }
});
```

--------------------------------

### stringProxy(form, fieldName, options)

Source: https://superforms.rocks/api

Creates a string store for a string schema field. It may look redundant, but the option can be useful if you need to convert an empty string to null or undefined.

```APIDOC
## [PROXY] stringProxy(form, fieldName, options)

### Description
Creates a string store for a **string** schema field. It may look redundant, but the option can be useful if you need to convert an empty string to `null` or `undefined`.

### Method
PROXY

### Endpoint
stringProxy(form, fieldName, options)

### Parameters
#### Parameters
- **form** (SuperForm) - Required - The form object from superForm.
- **fieldName** (string) - Required - The name of the field in the schema.
- **options** (object) - Required - Configuration options.

#### Options
- **empty** ('null' | 'undefined') - Required - The value to convert an empty string to.
- **taint** (boolean | 'untaint' | 'untaint-form') - Optional - Control tainting behavior.

### Request Example
```typescript
import { superForm, stringProxy } from 'sveltekit-superforms';
import { untrack } from 'svelte';
let { data } = $props();

const { form } = superForm(untrack(() => data.form));
const proxy = stringProxy(form, 'field', { options });
```

### Response
#### Success Response (200)
- **proxy** (Writable<string>) - A writable string store that syncs with the form field.

#### Response Example
```typescript
// The proxy is a writable store that can be used in the view.
```
```

--------------------------------

### formFieldProxy example for 'name' field

Source: https://superforms.rocks/components

Use formFieldProxy to produce proxies for path, value, errors, and constraints for a single field. It takes the superForm object as an argument, so you cannot immediately deconstruct what you need from superForm.

```svelte
<script lang="ts">
  import type { PageData } from './$types.js';
  import { superForm, formFieldProxy } from 'sveltekit-superforms/client';
  import { untrack } from 'svelte';

  let { data } : { data: PageData } = $props();

  const superform = superForm(untrack(() => data.form));

  const { path, value, errors, constraints } = formFieldProxy(superform, 'name');
</script>
```

--------------------------------

### onResult

Source: https://superforms.rocks/concepts/events

Documentation for the onResult event callback in sveltekit-superforms.

```APIDOC
## onResult

### Description
Called when the form is posted to the server and a SvelteKit ActionResult is received, if the submission isn't cancelled and client-side validation succeeds. Allows you to modify the result, access the form element, or cancel the rest of the event chain.

### Callback Signature
`onResult: ({ result, formElement, cancel }) => void`

### Parameters
- **result** (ActionResult) - The SvelteKit ActionResult. Can be modified; changes are applied further down the event chain.
- **formElement** (HTMLFormElement) - The form's HTML element.
- **cancel** (function) - Cancels the rest of the event chain and any form updates.

### Common Usage
Useful when `applyAction = false` and you still want to redirect, since the form doesn't do that automatically. Also, when `applyAction` is `false`, `$page.status` won't update, but the status code is available in `result.status`.

### Example
```js
const { form, enhance } = superForm(data.form, {
  applyAction: false,
  onResult({ result }) {
    if (result.type === 'redirect') {
      goto(result.location);
    }
  }
});
```
```
Tokens:
Raw