Building Custom Widgets with TagoAI

Use TagoAI to build a Custom Widget from a written description. Describe what you want users to see and do; TagoAI can create the widget and its code. This tutorial covers what to put in the prompt and how to check the result against your device data.

In this example, TagoAI built a temperature history widget on a Blueprint dashboard and summarized the result in the chat, including the blueprint slot and variable it used, the number of records, and the widget size.

Before you start

• Make sure TagoAI is enabled for the profile under Profile Settings → Services → AI Provider. On profiles in the EU region, it is off by default. See TagoAI for models, AI Credits, and providers.
• Review TagoAI Chat to choose a model and a permission mode appropriate for creating or editing resources.
• Have a Normal or Blueprint dashboard ready, along with the device data you want to display.

For this walkthrough, use a test dashboard and a device with temperature and door-state data. Replace the example names and values with those from your application.

1. Define the result

Before asking TagoAI to build anything, decide:

• Purpose: What should someone understand or do with this widget?
• Data: Which device or blueprint slot and which variables should it use?
• Layout: What information matters most, especially on mobile?
• Interactions: Is it display-only, or should users be able to submit changes?
• Missing data: What should appear when a value is unavailable?

Start with a display-only widget. Review its data and layout before adding controls.

2. Ask TagoAI to create the widget

Open your dashboard in the Admin, then open TagoAI from the dashboard. This gives the chat context about the dashboard you are viewing.

Explicitly ask for a Custom Widget and describe the expected result:

Create a Custom Widget on this dashboard for the device Cold Room 4.

The widget should help an operator check the room's temperature
and whether its door is open.

Use:
- temperature, in °C
- door_state, with values open or closed

Show:
- The latest temperature as the main value, with its timestamp.
- Door state as a clearly labeled badge.
- A temperature chart covering the last 24 hours, where data
  is available.

Use a compact layout with the current values above the chart.
On mobile, stack the content without horizontal scrolling.

Show "No data available" for missing values rather than displaying
zero or assuming the door is closed.

Do not add controls yet.

For a Blueprint dashboard, name the intended blueprint slot in your prompt. See Blueprint Dashboard for device-selection and configuration guidance.

3. Review the first version

Compare the result with your requirements and actual device records:

• Does TagoAI's summary in the chat match your request, including the data binding, the number of records, and the widget size?
• Do the displayed values, units, and timestamps match?
• Does the chart show the intended period? If not, is the available history clear?
• Can users identify the most important information without scrolling?
• Is the widget readable at its actual desktop and mobile sizes?
• Are missing values distinguishable from valid readings?
• On a Blueprint dashboard, does each entry in the widget's Data sources use the blueprint slot rather than a fixed device?

Do not judge the result only by its appearance. Check the data before refining the design.

If something is wrong, describe the expected and actual behavior. To get a diagnosis without changes, switch to Read Only first, because Edit Mode can apply changes without asking:

The latest temperature matches the device data, but the chart only
shows about one hour. I requested 24 hours.

Check the available history and the widget configuration. Explain
what is limiting the displayed period before making changes.

4. Refine with focused requests

Ask for one related set of changes at a time. State what should remain unchanged:

Keep the existing values, chart, and data sources.

On mobile, move the door-state badge below the temperature and
reduce the timestamp size. Keep both current values visible
above the chart.

After each revision, check both the requested change and the features that should have stayed the same.

If you add controls, specify the device and variable each control writes, allowed values, confirmation step, and expected feedback. The variable must be one of the widget's data sources; otherwise the write is dropped without an error. Test controls with a non-production device before relying on them. To route commands through an Analysis and confirm them from field data, see Building SCADA-style HMIs with Custom Widgets.

5. Validate for your users

Before sharing the dashboard with users:

• Test desktop and mobile layouts.
• Check missing, incomplete, and unexpected data.
• For Blueprint dashboards, test several device selections.
• Test every control and verify its actual outcome.
• If TagoRUN users will open the dashboard, test it signed in as one of them.
• Review generated code and configuration as you would any other application change. The generated source is a .tsx file in the profile's Files, and its address appears in the widget's URL and parameters section.

When to use the development Skill

Consult the Custom Widget Development Skill when you need to:

• Inspect or edit the generated source.
• Build through an IDE or another AI client connected to the TagoIO MCP Server with a profile token.
• Investigate build, rendering, or data-integration problems.

The Skill contains the implementation requirements, supported dependency versions, SDK usage, upload constraints, and technical troubleshooting guidance. Refer to it directly rather than relying on copied examples of those requirements.

If you use another AI coding assistant, install the Skill as described in the MCP Server README, then ask the assistant to follow it before creating or changing the widget.