tejovanthn Conform Forms
This skill covers Conform v1+ patterns for building accessible, progressively enhanced forms in Remix with Zod validation.
Core Concepts
Conform Benefits:
- Progressive enhancement (works without JS)
- Type-safe with Zod integration
- Accessible by default (ARIA attributes)
- Controlled and uncontrolled modes
- File uploads
- Multi-step forms
- Field arrays (dynamic lists)
Key Terms:
- Form: Top-level form configuration
- Field: Individual form input
- Constraint: HTML5 validation attributes
- Submission: Form submission result
- Field Array: Dynamic list of fields
Installation
npm install @conform-to/react @conform-to/zod zod
Basic Form
Simple Form with Validation
// app/routes/login.tsx
import { getFormProps, getInputProps, useForm } from "@conform-to/react";
import { parseWithZod } from "@conform-to/zod";
import { Form, useActionData } from "@remix-run/react";
import { json, redirect } from "@remix-run/node";
import { z } from "zod";
// Define schema
const loginSchema = z.object({
email: z.string().email("Invalid email address"),
password: z.string().min(8, "Password must be at least 8 characters"),
remember: z.boolean().optional(),
});
export async function action({ request }: ActionFunctionArgs) {
const formData = await request.formData();
// Parse with Zod
const submission = parseWithZod(formData, { schema: loginSchema });
// Return errors if validation fails
if (submission.status !== "success") {
return json({ submission: submission.reply() });
}
// Process valid data
const { email, password, remember } = submission.value;
await login(email, password, remember);
return redirect("/dashboard");
}
export default function Login() {
const lastResult = useActionData<typeof action>();
const [form, fields] = useForm({
lastResult: lastResult?.submission,
onValidate: ({ formData }) => {
return parseWithZod(formData, { schema: loginSchema });
},
shouldValidate: "onBlur",
shouldRevalidate: "onInput",
});
return (
<Form method="post" {...getFormProps(form)}>
<div>
<label htmlFor={fields.email.id}>Email</label>
<input
{...getInputProps(fields.email, { type: "email" })}
key={fields.email.key}
/>
<div>{fields.email.errors}</div>
</div>
<div>
<label htmlFor={fields.password.id}>Password</label>
<input
{...getInputProps(fields.password, { type: "password" })}
key={fields.password.key}
/>
<div>{fields.password.errors}</div>
</div>
<div>
<label>
<input
{...getInputProps(fields.remember, { type: "checkbox" })}
key={fields.remember.key}
/>
Remember me
</label>
</div>
<button type="submit">Login</button>
</Form>
);
}
Form Configuration
useForm Hook Options
const [form, fields] = useForm({
// ID for the form (required for nested forms)
id: "login-form",
// Last submission result from action
lastResult: actionData?.submission,
// Default values
defaultValue: {
email: "user@example.com",
remember: true,
},
// Client-side validation
onValidate: ({ formData }) => {
return parseWithZod(formData, { schema: loginSchema });
},
// When to validate
shouldValidate: "onBlur", // or "onInput" | "onSubmit"
shouldRevalidate: "onInput", // after first validation
// Callbacks
onSubmit: (event, context) => {
// Optional: custom submit handling
// event.preventDefault() if you want to prevent submission
},
// Constraint validation (HTML5)
constraint: getZodConstraint(loginSchema),
});
Field Types
Text Input
const schema = z.object({
name: z.string().min(1, "Name is required"),
bio: z.string().max(500, "Bio is too long").optional(),
});
// In component
<div>
<label htmlFor={fields.name.id}>Name</label>
<input
{...getInputProps(fields.name, { type: "text" })}
key={fields.name.key}
/>
<div id={fields.name.errorId}>{fields.name.errors}</div>
</div>
<div>
<label htmlFor={fields.bio.id}>Bio</label>
<textarea
{...getTextareaProps(fields.bio)}
key={fields.bio.key}
rows={4}
/>
<div>{fields.bio.errors}</div>
</div>
Number Input
const schema = z.object({
age: z.number().min(18, "Must be 18 or older"),
price: z.number().positive("Price must be positive"),
});
<input
{...getInputProps(fields.age, { type: "number" })}
key={fields.age.key}
min={18}
max={120}
/>
Select/Dropdown
const schema = z.object({
role: z.enum(["STUDENT", "TEACHER", "ADMIN"]),
country: z.string().min(1, "Country is required"),
});
<select
{...getSelectProps(fields.role)}
key={fields.role.key}
>
<option value="">Select role</option>
<option value="STUDENT">Student</option>
<option value="TEACHER">Teacher</option>
<option value="ADMIN">Admin</option>
</select>
<div>{fields.role.errors}</div>
Checkbox
const schema = z.object({
terms: z.literal(true, {
errorMap: () => ({ message: "You must accept terms" }),
}),
newsletter: z.boolean().optional(),
});
<label>
<input
{...getInputProps(fields.terms, { type: "checkbox" })}
key={fields.terms.key}
/>
I accept the terms and conditions
</label>
<div>{fields.terms.errors}</div>
Radio Buttons
const schema = z.object({
plan: z.enum(["free", "pro", "enterprise"]),
});
<fieldset>
<legend>Choose a plan</legend>
<label>
<input
{...getInputProps(fields.plan, { type: "radio" })}
value="free"
/>
Free
</label>
<label>
<input
{...getInputProps(fields.plan, { type: "radio" })}
value="pro"
/>
Pro
</label>
<label>
<input
{...getInputProps(fields.plan, { type: "radio" })}
value="enterprise"
/>
Enterprise
</label>
<div>{fields.plan.errors}</div>
</fieldset>
Date Input
const schema = z.object({
birthDate: z.string().refine(
(date) => {
const parsed = new Date(date);
return !isNaN(parsed.getTime());
},
{ message: "Invalid date" }
),
scheduledDate: z.string().refine(
(date) => new Date(date) > new Date(),
{ message: "Date must be in the future" }
),
});
<input
{...getInputProps(fields.birthDate, { type: "date" })}
key={fields.birthDate.key}
max={new Date().toISOString().split("T")[0]} // Today or earlier
/>
<input
{...getInputProps(fields.scheduledDate, { type: "datetime-local" })}
key={fields.scheduledDate.key}
/>
File Uploads
Single File Upload
const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
const schema = z.object({
avatar: z
.instanceof(File)
.refine(
(file) => file.size <= MAX_FILE_SIZE,
"File size must be less than 5MB"
)
.refine(
(file) => ["image/jpeg", "image/png", "image/webp"].includes(file.type),
"Only JPEG, PNG, and WebP images are allowed"
),
});
export async function action({ request }: ActionFunctionArgs) {
const formData = await request.formData();
const submission = parseWithZod(formData, {
schema: schema.transform(async (data) => {
// Upload to S3
const url = await uploadToS3(data.avatar);
return { avatarUrl: url };
}),
async: true, // Required for async transforms
});
if (submission.status !== "success") {
return json({ submission: submission.reply() });
}
// Use submission.value.avatarUrl
await updateUser(userId, { avatarUrl: submission.value.avatarUrl });
return redirect("/profile");
}
// In component
<div>
<label htmlFor={fields.avatar.id}>Avatar</label>
<input
{...getInputProps(fields.avatar, { type: "file" })}
key={fields.avatar.key}
accept="image/jpeg,image/png,image/webp"
/>
<div>{fields.avatar.errors}</div>
</div>
Multiple File Upload
const schema = z.object({
photos: z
.array(z.instanceof(File))
.min(1, "At least one photo is required")
.max(5, "Maximum 5 photos allowed")
.refine(
(files) => files.every((file) => file.size <= MAX_FILE_SIZE),
"Each file must be less than 5MB"
),
});
<input
{...getInputProps(fields.photos, { type: "file" })}
key={fields.photos.key}
accept="image/*"
multiple
/>
Nested Objects
const schema = z.object({
name: z.string().min(1),
address: z.object({
street: z.string().min(1),
city: z.string().min(1),
zipCode: z.string().regex(/^\d{5}$/, "Invalid ZIP code"),
}),
});
export default function AddressForm() {
const [form, fields] = useForm({
onValidate: ({ formData }) => parseWithZod(formData, { schema }),
});
const address = fields.address.getFieldset();
return (
<Form method="post" {...getFormProps(form)}>
<input {...getInputProps(fields.name, { type: "text" })} />
<fieldset>
<legend>Address</legend>
<input
{...getInputProps(address.street, { type: "text" })}
placeholder="Street"
/>
<div>{address.street.errors}</div>
<input
{...getInputProps(address.city, { type: "text" })}
placeholder="City"
/>
<div>{address.city.errors}</div>
<input
{...getInputProps(address.zipCode, { type: "text" })}
placeholder="ZIP Code"
/>
<div>{address.zipCode.errors}</div>
</fieldset>
<button type="submit">Submit</button>
</Form>
);
}
Field Arrays (Dynamic Lists)
import { useFieldList } from "@conform-to/react";
const schema = z.object({
name: z.string().min(1),
emails: z
.array(
z.object({
address: z.string().email(),
primary: z.boolean().optional(),
})
)
.min(1, "At least one email is required"),
});
export default function EmailsForm() {
const [form, fields] = useForm({
onValidate: ({ formData }) => parseWithZod(formData, { schema }),
defaultValue: {
emails: [{ address: "", primary: true }],
},
});
const emails = useFieldList(form.ref, fields.emails);
return (
<Form method="post" {...getFormProps(form)}>
<input {...getInputProps(fields.name, { type: "text" })} />
<fieldset>
<legend>Email Addresses</legend>
{emails.map((email, index) => {
const emailFields = email.getFieldset();
return (
<div key={email.key}>
<input
{...getInputProps(emailFields.address, { type: "email" })}
placeholder="Email address"
/>
<div>{emailFields.address.errors}</div>
<label>
<input
{...getInputProps(emailFields.primary, { type: "checkbox" })}
/>
Primary
</label>
<button
{...form.remove.getButtonProps({
name: fields.emails.name,
index,
})}
>
Remove
</button>
</div>
);
})}
<button
{...form.insert.getButtonProps({
name: fields.emails.name,
})}
>
Add Email
</button>
</fieldset>
<button type="submit">Submit</button>
</Form>
);
}
Multi-Step Forms
const step1Schema = z.object({
email: z.string().email(),
password: z.string().min(8),
});
const step2Schema = z.object({
name: z.string().min(1),
bio: z.string().optional(),
});
const fullSchema = step1Schema.merge(step2Schema);
export async function action({ request }: ActionFunctionArgs) {
const formData = await request.formData();
const step = formData.get("_step");
if (step === "1") {
// Validate step 1
const submission = parseWithZod(formData, { schema: step1Schema });
if (submission.status !== "success") {
return json({ submission: submission.reply(), step: 1 });
}
// Move to step 2
return json({ submission: submission.reply(), step: 2 });
}
// Final submission - validate everything
const submission = parseWithZod(formData, { schema: fullSchema });
if (submission.status !== "success") {
return json({ submission: submission.reply(), step: 2 });
}
// Create account
await createAccount(submission.value);
return redirect("/dashboard");
}
export default function Signup() {
const actionData = useActionData<typeof action>();
const [currentStep, setCurrentStep] = useState(actionData?.step ?? 1);
const [form, fields] = useForm({
lastResult: actionData?.submission,
onValidate: ({ formData }) => {
const schema = currentStep === 1 ? step1Schema : fullSchema;
return parseWithZod(formData, { schema });
},
});
return (
<Form method="post" {...getFormProps(form)}>
<input type="hidden" name="_step" value={currentStep} />
{currentStep === 1 && (
<>
<h2>Step 1: Account Details</h2>
<input {...getInputProps(fields.email, { type: "email" })} />
<div>{fields.email.errors}</div>
<input {...getInputProps(fields.password, { type: "password" })} />
<div>{fields.password.errors}</div>
<button type="button" => setCurrentStep(2)}>
Next
</button>
</>
)}
{currentStep === 2 && (
<>
<h2>Step 2: Profile</h2>
<input {...getInputProps(fields.name, { type: "text" })} />
<div>{fields.name.errors}</div>
<textarea {...getTextareaProps(fields.bio)} />
<div>{fields.bio.errors}</div>
<button type="button" => setCurrentStep(1)}>
Back
</button>
<button type="submit">Create Account</button>
</>
)}
</Form>
);
}
Advanced Patterns
Dependent Fields
const schema = z
.object({
hasShippingAddress: z.boolean(),
shippingAddress: z.object({
street: z.string(),
city: z.string(),
}).optional(),
})
.refine(
(data) => {
if (data.hasShippingAddress) {
return data.shippingAddress?.street && data.shippingAddress?.city;
}
return true;
},
{
message: "Shipping address is required",
path: ["shippingAddress"],
}
);
export default function ShippingForm() {
const [form, fields] = useForm({
onValidate: ({ formData }) => parseWithZod(formData, { schema }),
});
const hasShipping = fields.hasShippingAddress.value === "on";
const shippingFields = fields.shippingAddress.getFieldset();
return (
<Form method="post" {...getFormProps(form)}>
<label>
<input
{...getInputProps(fields.hasShippingAddress, { type: "checkbox" })}
/>
Use different shipping address
</label>
{hasShipping && (
<fieldset>
<input {...getInputProps(shippingFields.street, { type: "text" })} />
<input {...getInputProps(shippingFields.city, { type: "text" })} />
</fieldset>
)}
<button type="submit">Submit</button>
</Form>
);
}
Custom Validation Messages
const schema = z.object({
email: z.string().email("Please enter a valid email address"),
password: z
.string()
.min(8, "Password must be at least 8 characters")
.regex(/[A-Z]/, "Password must contain an uppercase letter")
.regex(/[a-z]/, "Password must contain a lowercase letter")
.regex(/[0-9]/, "Password must contain a number"),
confirmPassword: z.string(),
}).refine(
(data) => data.password === data.confirmPassword,
{
message: "Passwords don't match",
path: ["confirmPassword"],
}
);
Server-Side Only Validation
const clientSchema = z.object({
email: z.string().email(),
username: z.string().min(3),
});
const serverSchema = clientSchema.extend({
email: z.string().email().refine(
async (email) => {
const existing = await db.user.findUnique({ where: { email } });
return !existing;
},
{ message: "Email already registered" }
),
});
export async function action({ request }: ActionFunctionArgs) {
const formData = await request.formData();
// Server-side validation with async checks
const submission = await parseWithZod(formData, {
schema: serverSchema,
async: true,
});
if (submission.status !== "success") {
return json({ submission: submission.reply() });
}
// Create user
await createUser(submission.value);
return redirect("/login");
}
export default function Signup() {
const actionData = useActionData<typeof action>();
const [form, fields] = useForm({
lastResult: actionData?.submission,
// Client-side validation (no async checks)
onValidate: ({ formData }) => parseWithZod(formData, { schema: clientSchema }),
});
return <Form method="post" {...getFormProps(form)}>...</Form>;
}
Field-Level Intent (Blur/Change Events)
import { useInputControl } from "@conform-to/react";
export default function UsernameField({ field }) {
const control = useInputControl(field);
const [availability, setAvailability] = useState<"available" | "taken" | null>(null);
const checkAvailability = async (username: string) => {
const response = await fetch(`/api/check-username?username=${username}`);
const data = await response.json();
setAvailability(data.available ? "available" : "taken");
};
return (
<div>
<input
{...getInputProps(field, { type: "text" })}
=> {
if (control.value) {
checkAvailability(control.value);
}
}}
/>
{availability === "available" && <span>✓ Available</span>}
{availability === "taken" && <span>✗ Already taken</span>}
<div>{field.errors}</div>
</div>
);
}
Accessibility
Conform automatically generates accessible forms:
// Generated HTML includes:
<form id="login-form" aria-invalid={form.errors ? true : undefined}>
<label htmlFor="email-input">Email</label>
<input
id="email-input"
name="email"
type="email"
aria-invalid={fields.email.errors ? true : undefined}
aria-describedby={fields.email.errors ? "email-error" : undefined}
/>
<div id="email-error" aria-live="polite">
{fields.email.errors}
</div>
</form>
Manual Accessibility
<div>
<label htmlFor={fields.email.id}>
Email
<span aria-label="required">*</span>
</label>
<input
{...getInputProps(fields.email, { type: "email" })}
aria-required="true"
aria-describedby={`${fields.email.errorId} email-hint`}
/>
<div id="email-hint">We'll never share your email</div>
<div id={fields.email.errorId} aria-live="polite">
{fields.email.errors}
</div>
</div>
Testing
import { parseWithZod } from "@conform-to/zod";
import { describe, test, expect } from "vitest";
describe("Login form", () => {
test("validates email format", () => {
const formData = new FormData();
formData.set("email", "invalid");
formData.set("password", "password123");
const submission = parseWithZod(formData, { schema: loginSchema });
expect(submission.status).toBe("error");
expect(submission.reply().error?.email).toBeDefined();
});
test("accepts valid data", () => {
const formData = new FormData();
formData.set("email", "user@example.com");
formData.set("password", "password123");
const submission = parseWithZod(formData, { schema: loginSchema });
expect(submission.status).toBe("success");
expect(submission.value).toEqual({
email: "user@example.com",
password: "password123",
});
});
});
Best Practices
- Always use key prop: Prevents React state issues
- Use getInputProps helpers: Ensures proper attributes
- Validate on blur first: Better UX than validating on every keystroke
- Return submission.reply(): Preserves form state on errors
- Use Zod constraints: Enables HTML5 validation
- Handle file uploads properly: Use async transforms
- Test validation logic: Unit test your schemas
- Accessibility first: Use semantic HTML and ARIA when needed
- Progressive enhancement: Forms work without JavaScript
- Type safety: Let TypeScript infer types from schemas
Common Gotchas
- Missing key prop: Causes hydration issues
- Not using reply(): Loses form state on validation errors
- Async validation on client: Use server-only schemas
- Large file uploads: Need streaming for files >4.5MB
- Field array re-renders: Use proper keys
- Nested object syntax: Use getFieldset() for nested objects
- File validation: Must use instanceof File, not z.string()
- Multi-step validation: Validate current step, not full schema
- Default values: Use defaultValue in useForm, not in schema
- Form reset: Use form.reset() or navigate to clear state