> ## Documentation Index > Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt > Use this file to discover all available pages before exploring further. # Web chat widgets and forms > Rich in-chat UI cards and structured data-collection forms an agent can show in web chat. Widgets and forms let an agent render rich UI inside a web chat instead of replying with plain text. A widget is a structured card (a product carousel, an order tracker, a one-time-code prompt); a form is a typed data-collection panel (inputs, ratings, selects) the user fills in and submits. Both are configured on the agent version and triggered by the LLM during a conversation. These render in the embeddable container described in [Web widgets overview](/web-widgets/overview). This page covers what the agent can show; the [Web widget](/web-widgets/overview) is where it appears. ## How the LLM triggers them Widgets and forms are exposed to the model as tools. The model decides when to call them, fills in the parameters, and the result is delivered to the chat UI. * **Widgets** become a tool named `show__widget` (for example `show_carousel_widget`). The tool's parameters are the widget's content fields, so the model both chooses to show the widget and supplies its data in one call. * **Forms** become a tool named `show_form_` (for example `show_form_contact_info`). The form tool takes no parameters — the field definitions live in the config, and the user fills them in. The tool description defaults to `Show the '' form to collect structured data from the user.` unless you set a custom `description`. The same catalog is available on both transports, with one delivery difference: | Transport | Delivery | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | WebRTC (live web chat) | The model gets the `show_*` tools live; calling one fires a LiveKit RPC that renders the widget/form in the open session. | | Rich text | The same `show_*` tools are offered; each call appends a `{type, data}` entry that is emitted in the response payload for the client to render. | On the rich-text path, a form is emitted with `type: "form"` and the full form definition as its `data`. A widget is emitted with `type: ""` and the model-supplied content as its `data`. ## Enabling widgets Widgets are configured under `built_in_tools.widgets` on the agent version. The `allowed` field is an optional list of widget types. | Field | Type | Default | Description | | --------- | ------------------- | ------- | ---------------------------------------------------------------------------------------- | | `allowed` | list of widget type | omitted | Widget types the agent may show. If omitted or `null`, **all** widget types are enabled. | ## Widget catalog `WidgetType` enumerates the available widgets: | Widget type | What it shows | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `detail` | A detail page: title, optional image, text/markdown body, optional price, and a source link. Good for product pages, recipes, or articles. | | `carousel` | A scrollable grid of items with images, optional pricing, ratings, and add-to-cart buttons. | | `info` | Structured key-value information in labeled sections, with optional action buttons and external links. | | `list` | A list of items with optional images, badges, and per-item buttons. Supports multi-select with checkboxes and auto-numbering. | | `action_grid` | A grid of quick-action buttons with icons for the user to pick from. | | `collect_otp` | A one-time-code entry prompt for a code sent to a masked destination. | | `collect_phone_number` | A phone-number entry prompt. | | `order_tracker` | An order status tracker with carrier, tracking number, dates, and line items. | | `comparison` | A side-by-side comparison of items by price and labeled attributes. | ### Carousel items Each item in a `carousel` carries an `id`, `title`, and `image` (required), plus optional `link`, `price`, `vipPrice` (a discounted/VIP price), and `rating` (a number such as `4.5`). The widget itself accepts `index` (starting item, default `0`), `window` (visible items, default `3`), and `show_add_to_cart` to render an **Add to Cart** button on each item. ### List items A `list` item carries an `id` and `title` (required), plus optional `subtitle`, `image`, `value` (right-aligned text such as a price), `strike_value` (strikethrough, e.g. an original price), `badge`, and per-item `actions`. Each action has a `label` and an `action` identifier sent back when clicked, plus an optional `dismiss` flag (default `true`) that closes the widget after the click. Set `selectable: true` to enable multi-select checkboxes and `numbered: true` to auto-number items; pair multi-select with `submit_label` (use `{n}` for the selected count) and `submit_action`. Each `action_grid` item takes an `id`, `label`, and `action_value` (sent back when clicked). The optional `icon` is one of: `suitcase`, `ruler`, `truck`, `credit`, `headset`, `star`, `reload`. The grid `title` defaults to `How can I help?`. The `status` field is one of `ordered`, `shipped`, `in_transit`, or `delivered`. Required fields are `order_id`, `status`, `carrier`, `tracking_number`, `ordered_date`, `estimated_delivery`, and `items` (each with `name`, `color`, `size`, `quantity`). ## Forms Forms are configured under `built_in_tools.forms`. The `forms` list must contain at least one form, and form IDs must be unique within the agent. ### Form definition | Field | Type | Default | Description | | -------------- | ------------- | -------- | --------------------------------------------------------------------------- | | `id` | string | required | Unique form ID within the agent. Used to name the `show_form_` tool. | | `name` | string | required | Display name in the builder UI. | | `description` | string | none | Tool description that tells the LLM when to show this form. | | `title` | string | none | Title shown in the rendered form. | | `submit_label` | string | `Submit` | Label on the submit button. | | `fields` | list of field | required | At least one field. Non-`display` field IDs must be unique within the form. | ### Field types `FormFieldType` enumerates the field types: | Field type | Renders as | | --------------- | ----------------------------------------------------------------------------------- | | `input` | A single-line text input. | | `textarea` | A multi-line text input. | | `boolean` | A yes/no toggle, labeled with `true_label` / `false_label`. | | `rating` | A star rating. `max_rating` sets the number of stars (between 2 and 10, default 5). | | `single_select` | A choice of one option from `options`. | | `multi_select` | A choice of multiple options from `options`. | | `display` | Read-only display text; not part of the submitted data. | ### Field reference | Field | Type | Default | Description | | -------------------- | ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | required | Unique identifier within the form, used as the JSON key in submission data. | | `type` | field type | required | One of the field types above. | | `label` | string | required | The field's label. | | `placeholder` | string | none | Placeholder text. | | `required` | boolean | `false` | Whether the field must be filled before submit. | | `default_value` | any | none | Prefilled value. String for `input`/`textarea`/`single_select`, bool for `boolean`, number for `rating`, list of strings for `multi_select`. | | `options` | list of `{label, value}` | none | Choices for `single_select` and `multi_select`. | | `display_mode` | `dropdown` \| `buttons` | `dropdown` | How `single_select`/`multi_select` options render. | | `allow_other` | boolean | none | When `true`, select fields add an **Other** choice with a free-text input. | | `true_label` | string | none | Label for the `true` button on a `boolean` field (e.g. `Yes`). | | `false_label` | string | none | Label for the `false` button on a `boolean` field (e.g. `No`). | | `max_rating` | integer | 5 | Number of stars on a `rating` field. Must be between 2 and 10. | | `validation` | string | none | Regex pattern for validating text input values. | | `validation_message` | string | none | Error message shown when validation fails. | The `validation` regex must be 200 characters or fewer, must compile, and may not contain nested quantifiers (such as `(a+)+`), which are rejected to avoid catastrophic backtracking. ## Limits | Limit | Value | | ------------------------------ | ----------------------- | | `rating` / `max_rating` stars | 2–10 (default 5) | | Minimum fields per form | 1 | | Minimum forms in `FormsConfig` | 1 | | `validation` regex length | 200 characters | | Form IDs | unique within the agent | | Non-`display` field IDs | unique within a form | ## Related The embeddable container where these widgets and forms render. How the web widget runs in text and voice mode and surfaces quick actions.