# Widget Schema

> Complete type definitions for the widget system.

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

---

Complete type definitions for the widget system.

## Widget (Container)

The root container for all widgets.

```typescript
interface Widget {
  type: "ui" | "html";
  interactive?: boolean;
  title?: string;
  html?: string;           // For type="html"
  json?: string;           // Original JSON for reference
  children?: WidgetNode[];
  actions?: WidgetActionButton[];
}
```

### Properties

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `type` | `"ui" \| "html"` | Widget type - structured UI or raw HTML | required |
| `interactive` | `boolean` | Whether the widget accepts user input | `false` |
| `title` | `string` | Optional title displayed above the widget | - |
| `html` | `string` | Raw HTML content (for type="html") | - |
| `children` | `WidgetNode[]` | Child nodes to render (for type="ui") | - |
| `actions` | `WidgetActionButton[]` | Action buttons in the footer | - |

---

## WidgetNode

A single UI component within a widget.

```typescript
interface WidgetNode {
  type: WidgetNodeType;
  
  // Content
  value?: string;
  label?: string;
  
  // Image
  src?: string;
  alt?: string;
  
  // Form fields
  name?: string;
  placeholder?: string;
  defaultValue?: string;
  defaultChecked?: boolean;
  options?: WidgetSelectOption[];
  
  // Styling
  variant?: string;
  gap?: number;
  
  // Layout
  children?: WidgetNode[];
  
  // Actions
  action?: WidgetAction;
  
  // Data binding (advanced)
  dataKey?: string;
}
```

### Node Types

#### Primitive Types (render literal values)

| Type | Description |
|------|-------------|
| `text` | Plain text display |
| `markdown` | Markdown-formatted text |
| `image` | Image display |
| `badge` | Small label for status/metadata |
| `button` | Action button |
| `input` | Text input field |
| `select` | Dropdown select |
| `checkbox` | Binary checkbox |
| `row` | Horizontal layout container |
| `col` | Vertical layout container |

#### Data-Bound Types (read from ToolInvocation.Data)

| Type | Description |
|------|-------------|
| `plan-list` | Renders plan steps from Data |
| `key-value` | Renders key-value pairs from Data |
| `status-badge` | Renders status badge from Data |

---

## WidgetAction

Represents an action triggered by user interaction.

```typescript
interface WidgetAction {
  type: string;
  payload?: Record<string, any>;
}
```

### Properties

| Name | Type | Description |
|------|------|-------------|
| `type` | `string` | Action type identifier (e.g., "confirm", "cancel", "submit") |
| `payload` | `object` | Optional data to send with the action |

---

## WidgetActionButton

A button in the widget's action bar.

```typescript
interface WidgetActionButton {
  label: string;
  action: WidgetAction;
  variant?: "default" | "secondary" | "outline" | "ghost" | "destructive";
}
```

### Properties

| Name | Type | Description | Default |
|------|------|-------------|---------|
| `label` | `string` | Button text | required |
| `action` | `WidgetAction` | Action to trigger on click | required |
| `variant` | `string` | Visual style variant | `"default"` |

---

## WidgetSelectOption

An option in a select dropdown.

```typescript
interface WidgetSelectOption {
  label: string;
  value: string;
}
```

---

## Go Types

The Go SDK provides equivalent types in `inference.sh/common-go/pkg/models`:

```go
// Widget types
const (
    WidgetTypeUI   = "ui"
    WidgetTypeHTML = "html"
)

// Node types
const (
    WidgetNodeTypeText     WidgetNodeType = "text"
    WidgetNodeTypeMarkdown WidgetNodeType = "markdown"
    WidgetNodeTypeImage    WidgetNodeType = "image"
    WidgetNodeTypeBadge    WidgetNodeType = "badge"
    WidgetNodeTypeButton   WidgetNodeType = "button"
    WidgetNodeTypeInput    WidgetNodeType = "input"
    WidgetNodeTypeSelect   WidgetNodeType = "select"
    WidgetNodeTypeCheckbox WidgetNodeType = "checkbox"
    WidgetNodeTypeRow      WidgetNodeType = "row"
    WidgetNodeTypeCol      WidgetNodeType = "col"
)
```