# Widgets Overview

> Learn how to design widgets in your agent experience.

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

---

Learn how to design widgets in your agent experience.

Widgets are the containers and components that come with the inference shell runtime. You can use prebuilt widgets, modify templates, or design your own to fully customize the agent UI in your product.

## Overview

Widgets provide a structured way to render rich UI elements in agent conversations. They support:

- **Interactive elements** - Forms, buttons, inputs, selects
- **Layout primitives** - Rows, columns, boxes with flexible spacing
- **Typography** - Text, titles, captions with styling variants
- **Visual elements** - Badges, images, icons, dividers
- **Actions** - Server-side and client-side event handling

## Architecture

Widgets are constructed with a single container (`Widget`), which contains many components (`WidgetNode`).

```
Widget (Container)
├── type: "ui" | "html"
├── title?: string
├── children: WidgetNode[]
└── actions?: WidgetActionButton[]
```

### Widget Types

| Type | Description |
|------|-------------|
| `ui` | Structured JSON - frontend renders WidgetNodes recursively |
| `html` | Raw HTML string - frontend renders directly (for generated content) |

## Quick Start

### Go SDK

```go
import "inference.sh/common-go/pkg/models"

widget := &models.Widget{
    Type:  models.WidgetTypeUI,
    Title: "Task Complete",
    Children: []models.WidgetNode{
        {Type: models.WidgetNodeTypeText, Value: "Your task was completed successfully.", Variant: "muted"},
        {Type: models.WidgetNodeTypeBadge, Label: "success", Variant: "secondary"},
    },
}
```

### Widget Response

Widgets are attached to tool invocations:

```go
toolInvocation.Widget = widget
```

## Handle Actions

Widget actions allow users to trigger logic from the UI. Actions can be bound to different events on various widget nodes (e.g., button clicks) and then handled by your server.

```go
widget := &models.Widget{
    Type: models.WidgetTypeUI,
    Actions: []models.WidgetActionButton{
        {
            Label:   "Confirm",
            Variant: "default",
            Action: models.WidgetAction{
                Type:    "confirm",
                Payload: map[string]interface{}{"id": 123},
            },
        },
    },
}
```

## Reference

Use the component documentation to see all available options:

### Containers
- [Card](/docs/agents/widgets/card) - A bounded container for widgets

### Layout
- [Row](/docs/agents/widgets/row) - Arranges children horizontally
- [Col](/docs/agents/widgets/col) - Arranges children vertically

### Typography
- [Text](/docs/agents/widgets/text) - Displays plain text with styling
- [Markdown](/docs/agents/widgets/markdown) - Renders markdown-formatted text

### Controls
- [Button](/docs/agents/widgets/button) - A flexible action button
- [Input](/docs/agents/widgets/input) - Text input field
- [Select](/docs/agents/widgets/select) - Dropdown single-select input
- [Checkbox](/docs/agents/widgets/checkbox) - Binary selection control

### Content
- [Image](/docs/agents/widgets/image) - Displays an image
- [Badge](/docs/agents/widgets/badge) - A small label for status or metadata

### Actions
- [Actions](/docs/agents/widgets/actions) - Handle user interactions