🌵 Svelte Zod Form

Building forms in Svelte with breeze, using Zod

Example

REPL: Simple login form

Installation

NPM

1npm i @nerd-coder/svelte-zod-form

JSR (Recommended)

1npx jsr add @nerd-coder/svelte-zod-form

How to use

First you need to create a Zod's schema

1import { z } from 'zod'
2
3const loginSchema = z.object({
4  email: z.string().email(),
5  pass: z.string().min(4),
6})

Then pass the schema to ZodFormStore:

1const form = new ZodFormStore(loginSchema, { onSubmit: v => console.log('Submitted values:', v) })

All the field's handler, value will be generated and typed for you:

1// We need pull the generated field store out, in order
2// to use the Svelte's "auto subscription" feature "$"
3const { email_value, email_error, email_dirty, pass_value, pass_error, pass_dirty } = form.stores

Finally, use it in html

1<form on:submit|preventDefault={form.triggerSubmit}>
2  <fieldset>
3    <input
4      name="email"
5      on:input={form.fields.email.handleChange}
6      on:blur={form.fields.email.handleBlur}
7      value={$email_value || ''}
8      class:invalid={!!$email_error}
9      class:valid={!$email_error && !!$email_dirty}
10    />
11    {#if $email_error}<p>{$email_error}</p>{/if}
12  </fieldset>
13
14  <fieldset>
15    <input
16      name="pass"
17      type="password"
18      on:input={form.fields.pass.handleChange}
19      on:blur={form.fields.pass.handleBlur}
20      value={$pass_value || ''}
21      class:invalid={!!$pass_error}
22      class:valid={!$pass_error && !!$pass_dirty}
23    />
24    {#if $pass_error}<p>{$pass_error}</p>{/if}
25  </fieldset>
26
27  <button type="submit">Sign In</button>
28</form>

Configuration

initialValue

• type: Partial<T>
• required: false
• default: undefined

The initial data in the form. Will revert to this value if call form.reset.

1const form = new ZodFormStore(schema, {
2  initialValue: { email: 'my@email.com' },
3  ...
4})

onSubmit

• type: (v: T) => Promise<void | string> | string | void
• required: true

Async callback to handle submmition of the form. Should return nothing, or an string contain error message

1const form = new ZodFormStore(schema, {
2  onSubmit: (values) => console.log('Submitted values:', values),
3  ...
4})

debug

• type: boolean
• required: false
• default: false

Print various debug messages.

1const form = new ZodFormStore(schema, {
2  debug: true,
3  ...
4})

API

Prop	Type	Description
model	Readable<T>	Form's data. Will be passed to onSubmit handler
options	readonly ZodFormStoreOptions<T>	Form settings. Should not be update
triggerSubmit	() => Promise<void>	Function to start parsing, validating and submit the form's data
setupAutoSubmit	(delay: number) => Unsubscriber	Setup auto submit on every change of the model
reset	() => void	Function to reset the form to original state.
submitting	Readable<boolean>	True of submitting the form.
error	Readable<string>	Error message returned from onSubmit handler, or custom validation message.
errors	Readable<string[]>	Array of string contains all error messages (including fields's errors and error return from onSubmit handler).
dirty	Readable<boolean>	Indicate if the form is edited or submitted.
valid	Readable<boolean>	Indicate if the form is valid.
fields	object	Generated fields's functions.
stores	object	Generated fields's stores.

Generated stores's props

Prop	Type	Description
stores.fieldName_value	Readable<T['fieldName']>	Readable store holding field's value
stores.fieldName_touched	Readable<boolean>	The field have been touched or not
stores.fieldName_dirty	Readable<boolean>	The field value been changed or not
stores.fieldName_error	Readable<string>	The field validation error message, if any
stores.fieldName_valid	Readable<boolean>	The field value is valid or not

Generated field's functions

Prop	Type	Description
fields.fieldName.updateValue	(updater: Updater<T['fieldName']>) => void	Function to update field's value
stores.fieldName.setValue	(val: T['fieldName']) => void	Function to set field's value
stores.fieldName.handleChange	(val: unknown) => void	Callback to update field's value
stores.fieldName.handleBlur	() => void	Callback to mark field as touched
stores.fieldName.reset	() => void	Reset field to original state
stores.fieldName.setError	(msg: string) => void	Manually set field error
stores.fieldName.setTouched	(val: boolean) => void	Manually set touched state

Features

• Use Svelte native stores
• Fast: only update what changed, and you only subscribe to what you need
• Validation using Zod (Peer dependencies)
• TypeScript
• Minimal

Extra

Why the cactus 🌵?

> For its resilience

TODO

• More tests
• Support nested object
• Support array

Contributions

Any contributions are highly appreciate, please make a pull-request. If you would like to discuses a new feature, please create an issue first.