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

# Widgets Overview

> Build interactive UI components that your AI agent can display inline during conversations — forms, cards, tables, charts, and more.

## What are Widgets?

Widgets are interactive UI components that your AI agent can display inline during conversations. Instead of responding with plain text, the AI agent renders rich elements — forms, cards, tables, charts, buttons, and more — directly in the chat.

This lets your AI agent collect structured input, present data visually, and trigger actions, all without leaving the conversation.

## What You Can Do with Widgets

> [card] Collect Structured Input
>
> Build forms with text inputs, dropdowns, date pickers, checkboxes, and other controls to gather data from users.

> [card] Display Rich Content
>
> Show cards, tables, charts, images, and Markdown-formatted text to present information clearly.

> [card] Trigger Actions
>
> Connect buttons and form submissions to API calls, chat messages, URL navigation, or data updates.

> [card] React to User Input
>
> Use conditions to show, hide, or switch views based on the current values in the Widget.

> [card] Import and Export
>
> Share Widgets across AI agents and teams by exporting and importing `.widget` files.

> [card] AI-Assisted Building
>
> Generate Widgets from natural language descriptions or start from pre-built templates.

## Key Concepts

Understanding these core concepts will help you build and configure Widgets effectively.

| Concept | Description |
| - | - |
| **Code** | The visual layout of the Widget, written using a built-in component library. |
| **Schema** | Defines the data fields the Widget expects from the AI agent and their types. |
| **Default Example** | Initial values for all fields when the Widget first renders. |
| **Named Examples** | Saved data presets for previewing different scenarios in the builder. |
| **Functions** | Actions attached to interactive elements that define what happens on interaction. |
| **States** | Named wrappers whose visibility is controlled by conditions based on current values. |

> [!NOTE]
>
> The **Schema** is how the AI agent knows what data to pass into the Widget. Each field in the schema maps to a variable you can reference in the Widget code.

## Connecting Widgets to Actions

Widgets are always attached to an **Action**. You create and manage Widgets from within the [Custom Action](https://chatbase.co/docs/user-guides/chatbot/actions/custom-action.md) configuration page.

When creating a Custom Action, select the **Server with UI (Widget)** or **Widget only (UI only)** Action type to attach a Widget. The Action type determines how data flows into the Widget. There are two types:

> [tab] Widget-Only Actions
>
> These Actions have **no API URL** configured. The Widget receives data directly from the Action's input fields.
>
> You can either sync inputs with the Widget schema automatically or define them manually.
>
> **Best suited for:**
>
> * Forms that collect user input
> * Informational cards and menus
> * Interactive elements that don't need external data

> [tab] Server Actions with Widgets
>
> These Actions have an **API URL** configured. The Action calls your API first, then displays the Widget using the response data.
>
> **Best suited for:**
>
> * Data lookups (order status, account details)
> * Live data displays (inventory, analytics)
> * Multi-step workflows that depend on server-side logic

### Data Flow for Server Actions

**1. AI agent triggers the Action**

The AI agent decides to trigger the Action and provides the required input data.

**2. Action calls the API**

The Action sends a request to your configured API URL with the input data.

**3. API returns a response**

Your server processes the request and returns a JSON response.

**4. Response is merged with Action input**

The API response is combined with the original Action input data. If both contain the same field, the API response takes priority.

**5. Widget renders with combined data**

The Widget receives the merged data and renders the UI accordingly.

## Where Widget Data Comes From

When a Widget renders, its data can come from multiple sources. Higher-priority sources override lower ones.

| Priority | Source | Description |
| - | - | - |
| 1 (lowest) | **Default example** | The Widget's default values defined in the builder. |
| 2 | **Action input** | Data from the Action's configured input fields. |
| 3 (highest) | **API response** | Data returned from the API call (server Actions only). |

> [!NOTE]
>
> If a field is present in both the Action input and the API response, the API response value wins. Default example values are only used when no other source provides the field.

## File Uploads

Widgets can collect files from the visitor and send them straight to an endpoint you control, then show or reuse the uploaded file URLs. Add a `Dropzone` or `FileInput` component and an **Upload file** function. See [File Uploads](https://chatbase.co/docs/developer-guides/widgets/file-uploads.md).

## AI Response Transform

Sometimes the data returned by your API doesn't match the Widget's schema exactly. The **AI Response Transform** uses AI to automatically map the API response fields to the Widget's expected schema.

> [!TIP]
>
> The AI Response Transform is especially useful when you're connecting to third-party APIs where you don't control the response format, or when your API returns nested or differently-named fields that need to be flattened into the Widget schema.

## Import and Export

You can share Widgets between AI agents, teams, or projects using `.widget` files.

> [accordion] Exporting a Widget
>
> 1. Open the Widget in the builder.
> 2. Click the **more options** menu (three dots) in the top-right corner.
> 3. Select **Export** to download the Widget as a `.widget` file.
>
> The exported file contains the Widget's code, schema, default example, named examples, functions, and states.

> [accordion] Importing a Widget
>
> 1. Navigate to **Build > Widgets**.
> 2. Click the **Import** button.
> 3. Upload a `.widget` file from your computer.
>
> The imported Widget will appear in your Widgets list and can be attached to any Action.

> [!WARNING]
>
> Imported Widgets do not include Action configurations. After importing, you'll need to attach the Widget to an Action and configure the data flow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.