# Widgets overview

> Interactive widgets are rich UI components — forms, product carousels, order cards, tables — that your agent renders directly inside a chat instead of plain text. Build them with AI, a code editor, or from a template.

A **widget** is an interactive UI component that your agent renders inside the chat — a lead form, a shoppable product carousel, an order-status card, a booking picker, a data table. Instead of describing options in a wall of text, the agent shows a real interface the customer can tap, fill in, and submit, right in the conversation.

> **TWO DIFFERENT THINGS ARE CALLED "WIDGET":** The **website widget** is the embeddable chat bubble you put on your storefront — see [Deploy → Website widget](/docs/deploy/web-widget). **Widgets** (this section) are the interactive UI components the agent renders *inside* a chat. They are unrelated features that happen to share a name.

## Why use widgets

- **Higher conversion.** A one-tap "Add to cart" button or an inline booking picker resolves intent in the chat instead of bouncing the customer to another page.
- **Cleaner data capture.** A structured form (name, email, company size) returns clean, typed fields instead of free text the agent has to parse.
- **Faster resolution.** An order-status card or returns flow shows the answer visually, so the customer doesn't have to read and re-ask.
- **On-brand UI.** Widgets inherit a themed look (light/dark) automatically, so they match the chat surface without custom CSS.

## How widgets fit together

A widget has three parts: the **UI** (JSX-like markup over the built-in component library), a **data schema** (the typed inputs the widget expects), and optional **functions** (what happens when a button is pressed — send a message, open a link, set variables, or call your API). The agent renders a widget by attaching it to a [custom action](/docs/actions/custom-action); when that action runs, Bookbag merges the data and streams the rendered widget into the chat.

1. **Design the widget** — Describe it to the AI builder, start from a template, or write the markup yourself in the code editor.
2. **Define the data** — A schema declares the fields the widget needs (a product list, a title, options). A default example powers the live preview.
3. **Wire it to an action** — Attach the widget to a custom action. For server-backed widgets, the action calls your API first and merges the response into the widget data.
4. **The agent renders it** — When the agent invokes that action mid-conversation, the rendered widget appears inline and the customer can interact with it.

## Widget types

| Type | What it is | Use it for |
| --- | --- | --- |
| UI-only | Renders entirely from data the agent already has (or static content). No backend call. | Lead forms, contact forms, info cards, simple pickers. |
| Server | Calls your own API endpoint first, then merges the response into the widget before rendering. | Live order status, real product inventory, account details. |

> **INFO:** For server widgets, the merge order is **default example → action input → API response**, so live data from your endpoint always wins over the placeholder values used in the preview.

## Three ways to build

- [AI widget builder](/docs/widgets/ai-builder) — Describe the widget in plain language and let Bookbag generate the markup, schema, and example data.
- [Code editor](/docs/widgets/code-editor) — Write or refine the JSX-like markup directly, with a live preview and example data.
- [Components](/docs/widgets/components) — The full component library — layout, text, form inputs, data display, media, and interactive elements.

## Start from a template

The Widgets gallery ships ready-made, fully renderable templates you can duplicate and edit — including **Book a demo** (lead form), **Buy products** (shoppable carousel), product and class lists, a hotel/booking card, and a contact form with a submitted state. Each template includes working markup, a schema, and example data, so you can preview it immediately and adapt it to your store.

> **TIP:** Duplicating a template is the fastest way to learn the syntax — open one in the code editor, change the data, and watch the preview update.

## What's next

- [AI widget builder](/docs/widgets/ai-builder) — Generate a widget from a description.
- [Components](/docs/widgets/components) — Every component and how to compose them.
- [Custom action](/docs/actions/custom-action) — Wire a widget to an action so the agent can render it.