# Widgets and response mapping

Attach a reusable widget and connect the values it needs to display.

## Overview

Widgets turn an action result into an interactive card. Choose Call API + show widget when the card needs an API response, or Show widget when it can use fixed values and supplied inputs.

## Attach a widget

1. Open the Widget section of a compatible custom action.
2. Choose Add widget to create or select a widget, or upload a .widget file.
3. Review the selected widget and its declared input fields.
4. Connect the action data to those fields and check the preview.
5. Save and continue, then select channels and enable the action.

> **Shared widgets**: A selected widget is linked, not an independent copy. Editing a shared widget can affect every action using it. Review those actions before changing its inputs or layout.

## Connect data

For API widgets, first run a successful API test so you can inspect the response structure. Map the response values to the widget inputs, paying attention to field names, types, nested objects, and arrays. For Show widget, define any inputs the agent should supply and keep them aligned with the widget schema.

```json
{
  "page": {
    "title": "QwryAI deployment guide",
    "headings": ["Deploy your QwryAI agent", "Add the widget to your website", "Check the customer experience"]
  }
}
```

A page-help card can map its title and headings inputs from the page object. These values reflect the deployment guide used in the client-side action walkthrough. Use the actual response shape from your own API when mapping an API widget.

## Collect fields before showing a widget

For a conversational Show widget action, use Collect widget fields before showing it when the agent should obtain required information first. An action with automatic triggers displays immediately: the input-collection switch is disabled, so the widget must work with the data already available. Give optional fields useful defaults and check the empty-data state.

## Manage the linked widget

| Control | Purpose |
| --- | --- |
| Edit | Open the linked widget for changes. |
| Replace | Choose a different widget for the action. |
| Download | Export the widget for reuse. |
| Unlink | Remove the widget association from this action. |
| Upload widget | Import a .widget file from the empty widget section. |

## Check the customer experience

- Test with a complete response and with missing optional values.
- Check long labels, arrays with multiple items, and an empty result.
- Verify buttons and form controls on the deployed website.
- Check the narrow mobile layout and keyboard focus order.
- If the action is automatic, test its placement and dismissal settings too.

- [Automatic triggers](/docs/user-guides/actions/automatic-triggers)
- [Custom Action](/docs/user-guides/actions/custom-action)