openai/chatkit-python
Publicmirrored fromhttps://github.com/openai/chatkit-pythonAvailable
docs/concepts/widgets.md
54lines · modecode
| 1 | # Widgets |
| 2 | |
| 3 | Widgets are structured UI elements the assistant can stream into the conversation. They let you render forms, cards, lists, or other interactive components instead of plain text. |
| 4 | |
| 5 | ## Representation and delivery |
| 6 | |
| 7 | Here’s how a widget is represented from design time through runtime streaming. |
| 8 | |
| 9 | | Stage | What it contains | |
| 10 | | --- | --- | |
| 11 | | Working definition | [Widget UI language](#widget-ui-language) plus a schema (Zod/JSON) and example data you author in <https://widgets.chatkit.studio>. | |
| 12 | | Published definition | The exported [`.widget` file](#widget-files) bundling the layout, schema, and sample data. | |
| 13 | | Server runtime (definition only) | [`WidgetTemplate`](../api/chatkit/widgets.md#chatkit.widgets.WidgetTemplate) instance loaded from the `.widget` file. | |
| 14 | | Server runtime (hydrated) | [`DynamicWidgetRoot`](../api/chatkit/widgets.md#chatkit.widgets.DynamicWidgetRoot) or [`BasicRoot`](../api/chatkit/widgets.md#chatkit.widgets.BasicRoot) Pydantic model instance built from the template and real data. | |
| 15 | | Streamed to the client | The hydrated root serialized to JSON and included inside a [`WidgetItem`](../api/chatkit/types.md#chatkit.types.WidgetItem) streamed by `ChatKitServer`. | |
| 16 | | Rendered by the client | ChatKit.js deserializes the JSON into typed widget objects (for example, [`Card`](https://openai.github.io/chatkit-js/api/openai/chatkit-react/namespaces/widgets/type-aliases/card/) or [`ListView`](https://openai.github.io/chatkit-js/api/openai/chatkit/namespaces/widgets/type-aliases/listview/)) and renders them; entity previews use [`BasicRoot`](https://openai.github.io/chatkit-js/api/openai/chatkit-react/namespaces/widgets/type-aliases/basicroot/) returned from [`entities.onRequestPreview`](#entity-previews). | |
| 17 | | Sent as model input | A Responses API `Message` produced from a [`WidgetItem`](../api/chatkit/types.md#chatkit.types.WidgetItem) via [`ThreadItemConverter.widget_to_input`](../api/chatkit/agents.md#chatkit.agents.ThreadItemConverter.widget_to_input). | |
| 18 | |
| 19 | |
| 20 | ## Widget UI language |
| 21 | |
| 22 | Widget layouts use a strict, simplified JSX dialect that only allows specific components and props. Explore the available components and their props in <https://widgets.chatkit.studio/components> to see what the renderer supports. |
| 23 | |
| 24 | ### Containers |
| 25 | |
| 26 | Every widget must be wrapped in a root-level container element. For single, self-contained content such as a summary, confirmation, or form, use `<Card>`. For a set of options (for example, restaurants or files), use `<ListView>`. Reserve `<Basic>` for entity previews. |
| 27 | |
| 28 | - `<Card>`: Simple card with a light border and plain background; supports confirm and cancel actions. |
| 29 | - `<ListView>`: Scroll-friendly list with built-in “show more” mechanics. Children must be `<ListViewItem>`, and `<ListViewItem>` must only appear as a direct child of `<ListView>`; it has a constrained prop set for row-like layout (`children`, `gap`, `align`, `onClickAction`). |
| 30 | - `<Basic>`: Minimal container only used for entity previews. |
| 31 | |
| 32 | ## .widget files |
| 33 | |
| 34 | Exported `.widget` files are JSON blobs that include the widget template, the expected data schema, and supporting metadata. You can load them server-side and render widgets dynamically with `WidgetTemplate`; see [Build widgets with `WidgetTemplate`](../guides/build-interactive-responses-with-widgets.md#build-widgets-with-widgettemplate) for examples. |
| 35 | |
| 36 | ## WidgetItem |
| 37 | |
| 38 | [`WidgetItem`](../api/chatkit/types.md#chatkit.types.WidgetItem) represents a widget rendered as a [thread item](threads.md#what-are-thread-items) in the chat UI. In addition to a reference to the widget instance, it contains a `copy_text` field that represents the text value copied to the clipboard when the user clicks the copy button below the response. |
| 39 | |
| 40 | ## Entity previews |
| 41 | |
| 42 | The [`entities.onRequestPreview`](https://openai.github.io/chatkit-js/api/openai/chatkit-react/type-aliases/entitiesoption/#onrequestpreview) ChatKit option returns a preview typed as [`BasicRoot`](https://openai.github.io/chatkit-js/api/openai/chatkit-react/namespaces/widgets/type-aliases/basicroot/). |
| 43 | |
| 44 | |
| 45 | ## When to use |
| 46 | |
| 47 | - Collect structured input (forms) or present rich results (tables, cards, charts) that text alone cannot convey. |
| 48 | - Present the user with multiple choice options. |
| 49 | - Pair with actions to let users submit selections, confirm steps, or trigger server-side work. |
| 50 | - Mix with text to provide explanation plus an interactive control. |
| 51 | |
| 52 | ## Related guides |
| 53 | |
| 54 | - [Build interactive responses with widgets](../guides/build-interactive-responses-with-widgets.md) |
| 55 | |