> ## Documentation Index
> Fetch the complete documentation index at: https://artifactuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

> Interactive forms, wizards, and quick actions

## Overview

Form artifacts render interactive forms directly in the chat. Users can submit data back to the AI.

```json theme={null}
{
  "type": "form",
  "variant": "fields",
  "display": "inline",
  "title": "Contact Us",
  "submitLabel": "Send",
  "data": {
    "fields": [
      {"name": "email", "type": "email", "label": "Email", "required": true},
      {"name": "message", "type": "textarea", "label": "Message"}
    ]
  }
}
```

## Variants

### Fields

Standard form with input fields:

```json theme={null}
{
  "type": "form",
  "variant": "fields",
  "display": "inline",
  "title": "Feedback",
  "data": {
    "fields": [
      {"name": "rating", "type": "rating", "label": "How was your experience?"},
      {"name": "comments", "type": "textarea", "label": "Comments", "rows": 3}
    ]
  }
}
```

### Wizard

Multi-step form:

```json theme={null}
{
  "type": "form",
  "variant": "wizard",
  "display": "panel",
  "title": "Setup Wizard",
  "data": {
    "steps": [
      {
        "title": "Account",
        "fields": [
          {"name": "email", "type": "email", "label": "Email", "required": true}
        ]
      },
      {
        "title": "Profile",
        "fields": [
          {"name": "name", "type": "text", "label": "Name", "required": true}
        ]
      }
    ]
  }
}
```

### Buttons

Quick action buttons:

```json theme={null}
{
  "type": "form",
  "variant": "buttons",
  "display": "inline",
  "description": "How would you like to proceed?",
  "data": {
    "fields": [
      {"label": "Continue", "action": "continue", "variant": "primary"},
      {"label": "Cancel", "action": "cancel", "variant": "ghost"}
    ]
  }
}
```

## Display Modes

| Mode     | When to Use                          |
| -------- | ------------------------------------ |
| `inline` | Simple forms (1-3 fields), buttons   |
| `panel`  | Complex forms, wizards, file uploads |

## Field Types

| Type       | Description      |
| ---------- | ---------------- |
| `text`     | Single-line text |
| `email`    | Email input      |
| `password` | Password input   |
| `number`   | Numeric input    |
| `tel`      | Phone number     |
| `url`      | URL input        |
| `textarea` | Multi-line text  |
| `select`   | Dropdown         |
| `radio`    | Radio buttons    |
| `checkbox` | Checkbox         |
| `date`     | Date picker      |
| `time`     | Time picker      |
| `file`     | File upload      |
| `rating`   | Star rating      |
| `color`    | Color picker     |
| `range`    | Slider           |

## Field Properties

```json theme={null}
{
  "name": "username",
  "type": "text",
  "label": "Username",
  "placeholder": "Enter username",
  "required": true,
  "disabled": false,
  "defaultValue": "",
  "helpText": "Must be unique",
  "minLength": 3,
  "maxLength": 20,
  "pattern": "^[a-z0-9]+$"
}
```

## Select/Radio Options

```json theme={null}
{
  "name": "country",
  "type": "select",
  "label": "Country",
  "options": [
    {"value": "us", "label": "United States"},
    {"value": "uk", "label": "United Kingdom"},
    {"value": "ca", "label": "Canada"}
  ]
}
```

## Button Actions

Buttons in forms can have different actions:

| Action        | Description                                  | Form Behavior    |
| ------------- | -------------------------------------------- | ---------------- |
| `submit`      | Submit the form                              | Collapses with ✓ |
| `cancel`      | Cancel the form                              | Collapses with ✗ |
| `reset`       | Reset to default values                      | Stays active     |
| Custom string | Custom action (e.g., `"continue"`, `"skip"`) | Collapses with ✓ |

```json theme={null}
{
  "type": "buttons",
  "fields": [
    {"label": "Submit", "action": "submit", "variant": "primary"},
    {"label": "Reset", "action": "reset", "variant": "secondary"},
    {"label": "Cancel", "action": "cancel", "variant": "ghost"}
  ]
}
```

## Form Collapse Behavior

Inline forms automatically collapse after user interaction to keep the chat clean and prevent duplicate submissions.

### States

| State       | Icon | Description                             |
| ----------- | ---- | --------------------------------------- |
| `active`    | —    | Form is interactive                     |
| `submitted` | ✓    | User submitted or clicked action button |
| `cancelled` | ✗    | User clicked cancel                     |
| `inactive`  | —    | Historical form after page refresh      |

### Visual Appearance

When collapsed, forms display a compact bar showing:

* Status icon (checkmark, X, or dash)
* Form title

```
┌─────────────────────────────────┐
│  ✓  Contact Form                │
└─────────────────────────────────┘
```

### Page Refresh Behavior

After a page refresh:

* **Last message**: Forms stay active (user can still interact)
* **Older messages**: Forms collapse as "inactive"

This requires passing the `isLastMessage` prop to `ArtifactuseAgentMessage`:

```vue theme={null}
<ArtifactuseAgentMessage 
  v-for="(msg, index) in messages"
  :key="msg.id"
  :content="msg.content"
  :is-last-message="index === messages.length - 1"
/>
```

## Handling Submissions

<Tabs>
  <Tab title="Vue">
    ```vue theme={null}
    <ArtifactuseAgentMessage
      :content="content"
      @form-submit="handleSubmit"
      @form-cancel="handleCancel"
      @form-button-click="handleButtonClick"
    />

    <script setup>
    function handleSubmit({ formId, action, values, timestamp }) {
      console.log('Form submitted:', formId, values)
      // Send values to AI or API
    }

    function handleCancel({ formId, buttonName, timestamp }) {
      console.log('Form cancelled:', formId)
    }

    function handleButtonClick({ formId, action, buttonName, buttonLabel, values, timestamp }) {
      console.log('Custom button clicked:', action, buttonName)
      // Handle custom actions like "continue", "skip", etc.
    }
    </script>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    <ArtifactuseAgentMessage
      content={content}
      onFormSubmit={({ formId, action, values, timestamp }) => {
        console.log('Form submitted:', formId, values)
        // Send values to AI or API
      }}
      onFormCancel={({ formId, buttonName, timestamp }) => {
        console.log('Form cancelled:', formId)
      }}
      onFormButtonClick={({ formId, action, buttonName, buttonLabel, values, timestamp }) => {
        console.log('Custom button clicked:', action, buttonName)
        // Handle custom actions
      }}
    />
    ```
  </Tab>

  <Tab title="Svelte">
    ```svelte theme={null}
    <ArtifactuseAgentMessage
      content={content}
      on:form-submit={({ detail }) => {
        console.log('Form submitted:', detail.formId, detail.values)
      }}
      on:form-cancel={({ detail }) => {
        console.log('Form cancelled:', detail.formId)
      }}
      on:form-button-click={({ detail }) => {
        console.log('Custom button clicked:', detail.action, detail.buttonName)
      }}
    />
    ```
  </Tab>
</Tabs>

## Event Payloads

### form-submit

```typescript theme={null}
{
  formId: string      // Unique form identifier
  action: 'submit'    // Always 'submit'
  values: object      // Form field values { fieldName: value }
  timestamp: number   // Unix timestamp
}
```

### form-cancel

```typescript theme={null}
{
  formId: string        // Unique form identifier
  action: 'cancel'      // Always 'cancel'
  buttonName: string    // Button name or 'cancel'
  timestamp: number     // Unix timestamp
}
```

### form-button-click

```typescript theme={null}
{
  formId: string        // Unique form identifier
  action: string        // Custom action string (e.g., 'continue', 'skip')
  buttonName: string    // Button name or label
  buttonLabel: string   // Button display label
  values: object        // Current form field values
  timestamp: number     // Unix timestamp
}
```

## Styling Collapsed Forms

Collapsed forms use these CSS classes:

```css theme={null}
/* Base collapsed container */
.artifactuse-form--submitted { }
.artifactuse-form--cancelled { }
.artifactuse-form--inactive { }

/* Collapsed inner elements */
.artifactuse-form-collapsed { }
.artifactuse-form-collapsed-icon { }
.artifactuse-form-collapsed-title { }
```

Customize the appearance:

```css theme={null}
/* Custom success color for submitted forms */
.artifactuse-form--submitted {
  background: rgba(34, 197, 94, 0.1);
  border-color: rgba(34, 197, 94, 0.3);
}

.artifactuse-form--submitted .artifactuse-form-collapsed-icon {
  color: rgb(34, 197, 94);
}
```