Overview
The form system builds validated forms with Felte + Zod:
Formcontainer (context, schema, submit/change handlers)- Field wrappers:
FormInput,FormSelect,FormTextarea,FormDatepicker,FormCheckbox,FormRadio,FormFileUpload,FormClEditor - Shared
name/label/contextKeyfield 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.
| Prop | Type | Default | Description |
|---|---|---|---|
schema | Zod schema | z.object({}) | Validation schema |
initialValues | Record<string, any> | {} | Initial field values |
transform | (values) => any | identity | Transform values before submit |
validators | any[] | [] | Extra Felte validators |
onChange | (e: IFormChangeProp) => any | — | Fired when values / validity change |
onSubmit | (e: IFormSubmitProp) => any | — | Fired on submit |
contextKey | any | null | Extra context key (in addition to default) |
class | ClassValue | — | Classes on <form> |
children | Snippet<[initialValues, isValid, values]> | required | Form body |
IFormChangeProp<T>: { values: T; isValid: boolean; form: any }
IFormSubmitProp<T>: { values: T; context: any }
Shared Form* field props (IFormProps)
Every Form* field accepts:
| Prop | Type | Description |
|---|---|---|
name | string | Required. Field key in form values / schema |
label | string | Optional visible label |
contextKey | symbol | null | Must 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"
/> | Extra | Notes |
|---|---|
| Props | FormInputProps = 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
labelon eachForm*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)
| Prop | Type | Default | Description |
|---|---|---|---|
schema | Zod schema | z.object({}) | Validation schema |
initialValues | Record<string, any> | {} | Initial field values |
transform | (values) => any | identity | Transform values before submit |
validators | any[] | [] | Extra Felte validators |
onChange | (e: IFormChangeProp) => any | — | Values / validity changed |
onSubmit | (e: IFormSubmitProp) => any | — | Submit handler |
contextKey | any | null | Nested-form context key |
class | ClassValue | — | Classes on <form> |
children | Snippet<[initialValues, isValid, values]> | required | Form body |
Shared field props (IFormProps)
| Prop | Type | Description |
|---|---|---|
name | string | Required form field key |
label | string | Optional label |
contextKey | symbol | null | Match parent Form when nested |
Field wrappers
| Component | Underlying | Notes |
|---|---|---|
FormInput | Input | FormInputProps |
FormDatepicker | Datepicker | FormDatepickerProps |
FormSelect | Select | FormSelectProps |
FormTextarea | Textarea | FormTextareaProps |
FormCheckbox | Checkbox | + optional onChange |
FormRadio | Radio | Same name for groups |
FormFileUpload | FilePond | See File Upload |
FormClEditor | CL Editor | Rich text; height prop |