@goobits/forms

Production-ready forms for SvelteKit. Secure. Accessible. Done.

Choose Your Path

🚀 Quick Start - Ship a contact form in 5 minutes 📚 Documentation - Complete guides and API reference

Key Features

• Form Types - Contact, support, feedback, booking forms with category-based routing
• Schema Validation - Type-safe validation with Zod v4
• Bot Protection - reCAPTCHA v3, rate limiting, CSRF tokens
• File Uploads - Image uploads with preview and client-side validation
• Internationalization - i18n with Paraglide integration and auto-detection
• Accessibility - WCAG 2.1 compliant, tested with NVDA/JAWS/VoiceOver

Quick Start

Install

npm install @goobits/forms

Configure

// src/hooks.server.js
import { initContactFormConfig } from '@goobits/forms/config';

initContactFormConfig({
	appName: 'My App',
	categories: {
		general: {
			label: 'General Inquiry',
			fields: ['name', 'email', 'message']
		}
	}
});

Create API

// src/routes/api/contact/+server.js
import { createContactApiHandler } from '@goobits/forms/handlers/contactFormHandler';

export const POST = createContactApiHandler({
	adminEmail: process.env.ADMIN_EMAIL,
	fromEmail: process.env.FROM_EMAIL,
	emailServiceConfig: { provider: 'mock' } // or 'nodemailer', 'aws-ses'
});

Add Form

<!-- src/routes/contact/+page.svelte -->
<script>
	import { ContactForm } from '@goobits/forms/ui';
	import '@goobits/forms/ui/variables.css';
	import '@goobits/forms/ui/ContactForm.css';
</script>

<ContactForm apiEndpoint="/api/contact" />

Done! Start dev server and visit /contact.

🔒 Security

Build secure forms by validating data server-side. This package provides client-side checks for better UX, but security happens in your API handlers.

Included protections:

• CSRF token validation
• Rate limiting (IP-based, configurable)
• reCAPTCHA verification
• Input sanitization helpers
• File upload validation

See Getting Started Guide for production deployment.

Documentation

Getting Started

• Installation & Setup - Complete setup guide with reCAPTCHA, CSRF, and email configuration
• Configuration - All configuration options and providers
• TypeScript - Type-safe form development

API Reference

• Components - ContactForm, FeedbackForm, CategoryContactForm, FormField
• UI Components - Modals, Menus, Tooltips, Inputs
• Handlers - API route handlers and email services
• Security - CSRF protection, rate limiting

Guides

• Testing - Unit tests, E2E tests, mocking strategies
• Migration - Upgrade guides between versions
• Troubleshooting - Common issues and solutions

Examples

• Contact Form API Handler - Server-side handler with email delivery

Component Overview

Form Components

import {
	ContactForm,          // Main form with validation
	CategoryContactForm,  // Form with category selection
	ContactFormPage,      // Complete page layout
	FeedbackForm,         // Quick feedback widget
	FormField,            // Reusable field component
	UploadImage           // File upload with preview
} from '@goobits/forms/ui';

UI Components

import {
	Input, Textarea, SelectMenu, ToggleSwitch,  // Form inputs
	FormErrors, ThankYou,                        // Status components
	DemoPlayground                               // Interactive demo
} from '@goobits/forms/ui';

import { Menu, ContextMenu, MenuItem, MenuSeparator } from '@goobits/forms/ui';
import { Modal, Alert, Confirm, AppleModal } from '@goobits/forms/ui/modals';
import { tooltip, TooltipPortal } from '@goobits/forms/ui/tooltip';

See API Reference for complete component documentation with props and usage.

Styling

Import base styles and customize with CSS variables:

import '@goobits/forms/ui/variables.css';
import '@goobits/forms/ui/ContactForm.css';

.forms-scope {
	--color-primary-500: #3b82f6;
	--color-error-500: #ef4444;
	--font-family-base: 'Inter', system-ui, sans-serif;
	--border-radius-medium: 0.5rem;
}

See variables.css for all customization options.

Email Configuration

Development

emailServiceConfig: { provider: 'mock' }

Production (Nodemailer)

emailServiceConfig: {
	provider: 'nodemailer',
	smtp: {
		host: 'smtp.gmail.com',
		port: 587,
		secure: false,
		auth: {
			user: process.env.SMTP_USER,
			pass: process.env.SMTP_APP_PASSWORD
		}
	}
}

Production (AWS SES)

emailServiceConfig: {
	provider: 'aws-ses',
	region: 'us-east-1',
	accessKeyId: process.env.AWS_ACCESS_KEY_ID,
	secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
}

See Getting Started Guide for complete setup instructions.

Internationalization

Quick Override

<script>
	const messages = {
		howCanWeHelp: '¿Cómo podemos ayudarte?',
		sendMessage: 'Enviar mensaje',
		sending: 'Enviando...'
	};
</script>

<ContactForm {messages} />

Auto-Detection

// hooks.server.js
import { handleFormI18n } from '@goobits/forms/i18n';

export async function handle({ event, resolve }) {
	await handleFormI18n(event);
	return await resolve(event);
}

See Getting Started Guide for Paraglide integration.

Requirements

• Node.js ≥18.0.0
• pnpm ≥9.0.0 (or npm/yarn)
• SvelteKit project

Dependencies

All required dependencies install automatically:

npm install @goobits/forms

This includes: @sveltejs/kit, svelte, formsnap, sveltekit-superforms, zod, @lucide/svelte

Optional Email Service Dependencies

Choose one if you need email delivery:

npm install nodemailer          # For SMTP (Gmail, SendGrid, etc.)
npm install @aws-sdk/client-ses # For AWS SES

License

MIT - see LICENSE for details

Links

• Documentation - Complete guides and API reference
• Examples - Real-world implementations
• Changelog - Version history and migration guides
• GitHub Issues - Report bugs or request features
• npm Package - Latest releases

Built with: SvelteKit • Zod • Formsnap • Superforms