# Form

> Layout container optimized for form controls and submission.

**URL:** https://inference.sh/docs/agents/widgets/form
**Last updated:** 2026-09-18

---

Layout container optimized for form controls and submission.

## Preview

```
┌────────────────────────┐
│ Email                  │
│ [________________]     │
│                        │
│ Message                │
│ [________________]     │
│ [________________]     │
│                        │
│            [Submit]    │
└────────────────────────┘
```

## Usage

```go
node := models.WidgetNode{
    Type:      models.WidgetNodeTypeForm,
    Direction: "col",
    Gap:       3,
    OnSubmitAction: &models.WidgetAction{
        Type: "submit_form",
    },
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeInput, Name: "email", Placeholder: "Email"},
        {Type: models.WidgetNodeTypeButton, Label: "Submit", Submit: true},
    },
}
```

## Props

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `type` | `"form"` | Node type | required |
| `children` | `WidgetNode[]` | Form content | - |
| `onSubmitAction` | `ActionConfig` | Action dispatched on form submission | - |
| `direction` | `"row" \| "col"` | Flex direction for children | `"col"` |
| `gap` | `number \| string` | Gap between children | - |
| `align` | `string` | Cross-axis alignment | - |
| `justify` | `string` | Main-axis distribution | - |
| `padding` | `number \| string \| object` | Inner padding | - |
| `background` | `string \| ThemeColor` | Background color | - |
| `border` | `number \| object` | Border styling | - |
| `radius` | `string` | Border radius token | - |

## Examples

### Basic Form

```go
{
    Type:      models.WidgetNodeTypeForm,
    Direction: "col",
    Gap:       3,
    OnSubmitAction: &models.WidgetAction{Type: "submit"},
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeInput, Name: "email", Placeholder: "Email"},
        {Type: models.WidgetNodeTypeInput, Name: "password", Placeholder: "Password"},
        {Type: models.WidgetNodeTypeButton, Label: "Sign In", Submit: true},
    },
}
```

### Form with Labels

```go
{
    Type:      models.WidgetNodeTypeForm,
    Direction: "col",
    Gap:       4,
    OnSubmitAction: &models.WidgetAction{Type: "create_account"},
    Children: []models.WidgetNode{
        // Name field
        {Type: models.WidgetNodeTypeCol, Gap: 1, Children: []models.WidgetNode{
            {Type: models.WidgetNodeTypeLabel, Value: "Full Name", FieldName: "name"},
            {Type: models.WidgetNodeTypeInput, Name: "name", Required: true},
        }},
        // Email field
        {Type: models.WidgetNodeTypeCol, Gap: 1, Children: []models.WidgetNode{
            {Type: models.WidgetNodeTypeLabel, Value: "Email", FieldName: "email"},
            {Type: models.WidgetNodeTypeInput, Name: "email", Required: true},
        }},
        // Submit
        {Type: models.WidgetNodeTypeButton, Label: "Create Account", Submit: true, Block: true},
    },
}
```

### Form with Validation

```go
{
    Type:      models.WidgetNodeTypeForm,
    Direction: "col",
    Gap:       3,
    OnSubmitAction: &models.WidgetAction{Type: "submit"},
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeInput, Name: "email", Required: true, Pattern: "[^@]+@[^@]+"},
        {Type: models.WidgetNodeTypeCheckbox, Name: "terms", Label: "I accept the terms", Required: true},
        {Type: models.WidgetNodeTypeButton, Label: "Continue", Submit: true},
    },
}
```

## Form Submission

When a form is submitted:

1. All `required` fields are validated
2. `pattern` regex validation runs on relevant inputs
3. If valid, `onSubmitAction` is dispatched with form data
4. Form data includes all named fields

```json
{
  "email": "user@example.com",
  "name": "John Doe",
  "terms": true
}
```

## TypeScript

```typescript
const node: WidgetNode = {
  type: "form",
  direction: "col",
  gap: 3,
  onSubmitAction: { type: "submit" },
  children: [
    { type: "input", name: "email" },
    { type: "button", label: "Submit", submit: true },
  ],
}
```

## Best Practices

1. **Use submit button** - Set `Submit: true` on the submit button
2. **Add validation** - Use `required` and `pattern` for client-side validation
3. **Group with labels** - Wrap label + input in Col for proper layout
4. **Provide feedback** - Show success/error after submission