# FormBuilder API
URL: https://docs.forms.saastro.io/docs/formbuilder
> The recommended fluent API for building type-safe form configurations.
# FormBuilder API
`FormBuilder` is the recommended way to create form configurations. It provides a fluent, chainable API that validates your config at build time.
---
## Build a Form Step by Step
Let's build a real contact form progressively. Start simple, then add features one at a time.
### 1. Minimal Working Form
Every form needs a `formId`, at least one field, and at least one step:
```tsx
const uiComponents = import.meta.glob('@/components/ui/*.tsx', { eager: true });
const config = FormBuilder.create('contact')
.addField('name', (f) => f.type('text').label('Name').optional())
.addField('email', (f) => f.type('email').label('Email').optional())
.addStep('main', ['name', 'email'])
.build();
;
```
That's a working form. With no layout configured, fields render in a single column, and there are no validation constraints yet.
> **Every field needs a schema.** `FieldBuilder` requires a schema for every type except `'hidden'` — without one, `.build()` throws `FieldBuilder: field "name" requires a schema`. Calling any validation method satisfies this; `.optional()` is the minimal choice (it stores a ruleset with `required: false` and no other constraints).
### 2. Add Validation
Chain validation methods on each field:
```tsx
const config = FormBuilder.create('contact')
.addField('name', (f) => f.type('text').label('Name').required().minLength(2))
.addField('email', (f) => f.type('email').label('Email').required().email())
.addField('message', (f) => f.type('textarea').label('Message').required().minLength(10))
.addStep('main', ['name', 'email', 'message'])
.buttons({ submit: { type: 'submit', label: 'Send Message' } })
.build();
```
Now fields are validated before submission. See [Validation](/docs/validation) for all options.
### 3. Add Layout
Switch to manual layout for control over columns and spacing:
```tsx
const config = FormBuilder.create('contact')
.layout('manual')
.columns(12)
.gap(4)
.addField(
'name',
(f) => f.type('text').label('Name').required().minLength(2).columns({ default: 12, md: 6 }), // Full width on mobile, half on desktop
)
.addField('email', (f) =>
f.type('email').label('Email').required().email().columns({ default: 12, md: 6 }),
)
.addField(
'message',
(f) => f.type('textarea').label('Message').required().minLength(10).columns({ default: 12 }), // Always full width
)
.addStep('main', ['name', 'email', 'message'])
.buttons({ submit: { type: 'submit', label: 'Send Message' } })
.build();
```
See [Layout System](/docs/layout) for the full grid reference.
### 4. Add Submission Handling
Handle success, errors, and post-submit behavior:
```tsx
const config = FormBuilder.create('contact')
.layout('manual')
.columns(12)
.gap(4)
.addField('name', (f) =>
f.type('text').label('Name').required().minLength(2).columns({ default: 12, md: 6 }),
)
.addField('email', (f) =>
f.type('email').label('Email').required().email().columns({ default: 12, md: 6 }),
)
.addField('message', (f) =>
f.type('textarea').label('Message').required().minLength(10).columns({ default: 12 }),
)
.addStep('main', ['name', 'email', 'message'])
.buttons({ submit: { type: 'submit', label: 'Send Message' } })
.onSuccess(async (values) => {
await fetch('/api/contact', { method: 'POST', body: JSON.stringify(values) });
})
.onError((error) => console.error('Failed:', error.message))
.successMessage((values) => `Thanks ${values.name}! We'll reply to ${values.email}.`)
.build();
```
That's a complete, production-ready contact form. The sections below cover every method in detail.
---
## Creating a Builder
```tsx
const builder = FormBuilder.create('my-form-id');
```
The `formId` is required and must be unique per form. It's used for localStorage keys, analytics tracking, and plugin identification.
### build() vs buildUnsafe()
- `.build()` validates the config and throws descriptive errors if anything is missing
- `.buildUnsafe()` returns the partial config without validation (useful during development)
`.build()` checks:
- `formId` is set
- At least 1 field exists
- At least 1 step exists
- All fields referenced in steps exist
- `initialStep` (if set) references an existing step
---
## Layout Methods
Configure the form's grid layout. For full details, see [Layout System](/docs/layout).
```tsx
FormBuilder.create('form')
.layout('manual') // 'auto' | 'manual' (default: 'auto')
.columns(12) // 1-12 grid columns (or max columns in auto mode)
.gap(4) // Gap between fields (0-12, each unit = 0.25rem; default: 4)
.minFieldWidth(280) // Auto mode only: min field width in px (default: 240)
.layoutClassName('p-4'); // Stored in config; not yet applied to the grid by