Svelte Form System - Bitblue

A complete form system with validation, various input types, and submission handling built with Svelte and Zod.

Overview

The form system builds validated forms with Felte + Zod:

  • Form container (context, schema, submit/change handlers)
  • Field wrappers: FormInput, FormSelect, FormTextarea, FormDatepicker, FormCheckbox, FormRadio, FormFileUpload, FormClEditor
  • Shared name / label / contextKey field API

All Form* field components require a parent Form. They call getContext for Felte form state. Without a parent Form (or a matching contextKey), they will fail at runtime.

Setup

pnpm add @cailabs/components.forms felte
<script lang="ts">
	import { Form, FormInput } from '@cailabs/components.forms';
	import { Button } from '@cailabs/components.base';
	import * as z from 'zod';
</script>

See Installation for segment packages and peers.

Basic usage

<script lang="ts">
	import { Form, FormInput, Button, type IFormSubmitProp } from '.';
	import * as z from 'zod';

	const schema = z.object({
		username: z.string().min(3),
		email: z.string().email()
	});

	let initialValues = {
		username: '',
		email: ''
	};

	function handleSubmit(e: IFormSubmitProp<typeof initialValues>) {
		console.log('Form submitted:', e.values);
	}
</script>

<Form {schema} {initialValues} onSubmit={handleSubmit}>
	<FormInput name="username" label="Username" required />
	<FormInput name="email" label="Email" type="email" required />
	<Button type="submit">Submit</Button>
</Form>

Form

Container that manages Felte state, Zod validation, and context.

PropTypeDefaultDescription
schemaZod schemaz.object({})Validation schema
initialValuesRecord<string, any>{}Initial field values
transform(values) => anyidentityTransform values before submit
validatorsany[][]Extra Felte validators
onChange(e: IFormChangeProp) => any—Fired when values / validity change
onSubmit(e: IFormSubmitProp) => any—Fired on submit
contextKeyanynullExtra context key (in addition to default)
classClassValue—Classes on <form>
childrenSnippet<[initialValues, isValid, values]>requiredForm body

IFormChangeProp<T>: { values: T; isValid: boolean; form: any }
IFormSubmitProp<T>: { values: T; context: any }

Shared Form* field props (IFormProps)

Every Form* field accepts:

PropTypeDescription
namestringRequired. Field key in form values / schema
labelstringOptional visible label
contextKeysymbol | nullMust match parent Form contextKey when nested forms are used

Plus all props from the underlying presentational component (Input, Select, etc.), except name is owned by IFormProps.

FormInput

Wraps Input. Requires Form parent.

<FormInput
	name="email"
	label="Email Address"
	type="email"
	required
	placeholder="user@example.com"
/>
ExtraNotes
PropsFormInputProps = Omit<InputProps, 'name'> & IFormProps

FormDatepicker

Wraps Datepicker. Requires Form parent.

<FormDatepicker name="birthdate" label="Date of Birth" required />

FormSelect

Wraps Select. Requires Form parent.

<FormSelect name="country" label="Country" options={['USA', 'Canada', 'Mexico']} required />

FormTextarea

Wraps Textarea. Requires Form parent.

<FormTextarea name="bio" label="Biography" rows={4} />

FormCheckbox

Wraps Checkbox. Requires Form parent. Adds optional onChange.

<FormCheckbox name="subscribe" label="Subscribe to newsletter" />

FormRadio

Wraps Radio. Requires Form parent. Use multiple with the same name.

<FormRadio name="notification" value="email" label="Email" />
<FormRadio name="notification" value="sms" label="SMS" />

FormFileUpload

See File Upload. Requires Form parent. Props: FormFileUploadProps (name, label, title, …).

Nested forms / contextKey

When you nest multiple Forms, pass the same contextKey to the child Form and its Form* fields so they resolve the correct Felte context.

<script lang="ts">
	import { Form, FormInput } from '.';
	const nestedKey = Symbol('nested');
</script>

<Form>
	<FormInput name="outer" label="Outer" />
	<Form contextKey={nestedKey} schema={/* … */}>
		<FormInput name="inner" label="Inner" contextKey={nestedKey} />
	</Form>
</Form>

Validation

const schema = z.object({
	username: z.string().min(3, 'Must be at least 3 characters'),
	email: z.string().email('Invalid email address'),
	age: z.number().min(18, 'Must be at least 18 years old')
});

Layout

<Form class="space-y-4">
	<div class="grid grid-cols-1 gap-4 md:grid-cols-2">
		<FormInput name="firstName" label="First Name" />
		<FormInput name="lastName" label="Last Name" />
	</div>
</Form>

Event handling

onChange

<script lang="ts">
	import type { IFormChangeProp } from '.';

	function handleChange(e: IFormChangeProp<any>) {
		console.log('Current values:', e.values);
		console.log('Is valid:', e.isValid);
	}
</script>

<Form onChange={handleChange}>
	<!-- fields -->
</Form>

onSubmit

<script lang="ts">
	import type { IFormSubmitProp } from '.';

	function handleSubmit(e: IFormSubmitProp<any>) {
		console.log(e.values, e.context);
	}
</script>

<Form onSubmit={handleSubmit}>
	<!-- fields -->
</Form>

Accessibility

  • Prefer label on each Form* field so errors and controls stay associated.
  • Schema messages should be readable; Form helpers surface them under fields.
  • Submit buttons should be reachable by keyboard; do not disable without announcing why.

Complete example

<script lang="ts">
	import {
		Form,
		FormInput,
		FormDatepicker,
		FormSelect,
		Button,
		FormCheckbox,
		type IFormSubmitProp
	} from '.';
	import * as z from 'zod';

	const schema = z.object({
		firstname: z.string().min(1, 'Required'),
		lastname: z.string().min(1, 'Required'),
		email: z.string().email('Invalid email'),
		dob: z.string().min(1, 'Required'),
		gender: z.string().min(1, 'Required'),
		agree: z.boolean()
	});

	let initialValues = {
		firstname: '',
		lastname: '',
		email: '',
		dob: '',
		gender: '',
		agree: false
	};

	function handleSubmit(e: IFormSubmitProp<typeof initialValues>) {
		console.log('Submitting:', e.values);
	}
</script>

<div class="mx-auto max-w-md p-4">
	<Form {schema} {initialValues} onSubmit={handleSubmit} class="space-y-4">
		<div class="grid grid-cols-1 gap-4 md:grid-cols-2">
			<FormInput name="firstname" label="First Name" required />
			<FormInput name="lastname" label="Last Name" required />
		</div>

		<FormInput name="email" label="Email" type="email" required />
		<FormDatepicker name="dob" label="Date of Birth" required />
		<FormSelect name="gender" label="Gender" options={['Male', 'Female', 'Other']} required />

		<FormCheckbox name="agree" label="I agree to terms and conditions" required />

		<Button type="submit" class="w-full">Register</Button>
	</Form>
</div>

Props

Form (FormProps)

PropTypeDefaultDescription
schemaZod schemaz.object({})Validation schema
initialValuesRecord<string, any>{}Initial field values
transform(values) => anyidentityTransform values before submit
validatorsany[][]Extra Felte validators
onChange(e: IFormChangeProp) => any—Values / validity changed
onSubmit(e: IFormSubmitProp) => any—Submit handler
contextKeyanynullNested-form context key
classClassValue—Classes on <form>
childrenSnippet<[initialValues, isValid, values]>requiredForm body

Shared field props (IFormProps)

PropTypeDescription
namestringRequired form field key
labelstringOptional label
contextKeysymbol | nullMatch parent Form when nested

Field wrappers

ComponentUnderlyingNotes
FormInputInputFormInputProps
FormDatepickerDatepickerFormDatepickerProps
FormSelectSelectFormSelectProps
FormTextareaTextareaFormTextareaProps
FormCheckboxCheckbox+ optional onChange
FormRadioRadioSame name for groups
FormFileUploadFilePondSee File Upload
FormClEditorCL EditorRich text; height prop

© 2026 Bitblue is a registered trademark. All Rights Reserved.