Forms

Overview

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

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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

{
  "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 ✓

{
  "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:

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

Handling Submissions

Vue
React
Svelte

<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>

<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
  }}
/>

<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)
  }}
/>

Event Payloads

form-submit

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

form-cancel

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

form-button-click

{
  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:

/* 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:

/* 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);
}

Getting Started

Frameworks

Components

Artifacts

AI Prompts

Customization

Overview

Variants

Fields

Wizard

Buttons

Display Modes

Field Types

Field Properties

Select/Radio Options

Button Actions

Form Collapse Behavior

States

Visual Appearance

Page Refresh Behavior

Handling Submissions

Event Payloads

form-submit

form-cancel

form-button-click

Styling Collapsed Forms

​Overview

​Variants

​Fields

​Wizard

​Buttons

​Display Modes

​Field Types

​Field Properties

​Select/Radio Options

​Button Actions

​Form Collapse Behavior

​States

​Visual Appearance

​Page Refresh Behavior

​Handling Submissions

​Event Payloads

​form-submit

​form-cancel

​form-button-click

​Styling Collapsed Forms

Overview

Variants

Fields

Wizard

Buttons

Display Modes

Field Types

Field Properties

Select/Radio Options

Button Actions

Form Collapse Behavior

States

Visual Appearance

Page Refresh Behavior

Handling Submissions

Event Payloads

form-submit

form-cancel

form-button-click

Styling Collapsed Forms