> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/overview.md).

# Overview

The HTML Widget embeds a fully custom HTML + JavaScript page in a Blynk dashboard as a first-class widget. The page runs inside a Blynk host that exposes a JavaScript bridge, `BlynkBridge`. Through it your page can read and write datastream values, react to real-time updates, show the bound device's info and image, work with device metadata, tags, files, events, Data Engine queries and key-value storage, follow the app theme, and navigate to dashboard pages and native screens. No server-side code is needed.

Two kinds of host implement the bridge, and **they are not identical**:

| Host                                    | Transport                                                                    | Bridge script                       |
| --------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
| **Web** — Blynk Console dashboard       | A sandboxed `<iframe>` that talks to the dashboard with `window.postMessage` | Injected before your page's scripts |
| **Mobile** — Blynk Android and iOS apps | A native WebView with a JavaScript interface                                 | Injected before your page's scripts |

Capability flags, permission names and a few validation limits differ between the two. Each method entry notes its differences, and [Platform Differences](https://docs.blynk.io/en/html-widget-developer-guide/platform-differences.md) collects them in one place. **Never assume web behavior on mobile or the other way round — check the capability methods and feature-detect at runtime.**

### Generating widgets with AI

Blynk publishes `blynk-html-widget`, an [Agent Skill](https://agentskills.io) that teaches an AI coding agent how to build HTML widgets. It carries the BlynkBridge API reference, the platform constraints, and Blynk's visual style, so the agent produces a widget that works instead of guessing at the bridge.

1. Download the skill below.
2. Add it to your AI tool. The way to add depends on the exact tool.
3. Describe what you need in plain language: *"a gauge showing the temperature datastream with a 24-hour chart underneath"* and optionally send a screenshot reference if you have to get more precise result.
4. Copy the generated HTML into the editor's **Code** tab, then verify it on the **Testing** tab against a real device.

{% file src="/files/l3dXahswyD3nNgeJn2Bs" %}

{% hint style="warning" %}
**Note:** Always review generated code before adding the widget to a production dashboard. A generated widget can send values to your device, and the Testing tab uses a real device and real messages.
{% endhint %}

### How this reference is organized

The guide follows the layout of the Blynk Platform API reference: a getting-started part, then one page per area of the bridge, with one entry per method. Every method entry has the same parts:

* a one-line summary,
* the call signature,
* **Parameters** — name, type, whether it is required, and what it means,
* **Resolves with** — the value of a successful call,
* **Rejects with** — the `BlynkBridgeError` codes the call can fail with,
* an **Example**, and notes where the hosts differ.

| Page                                                                                                            | Methods                                                                                                                                                                                         |
| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Getting Started](https://docs.blynk.io/en/html-widget-developer-guide/getting-started.md)                      | How it works, skeleton, `new BlynkBridge()`, boot sequence                                                                                                                                      |
| [Host Capabilities](https://docs.blynk.io/en/html-widget-developer-guide/host-capabilities.md)                  | `isBridgeAvailable`, `isExternalRequestsAllowed`, `isRangePickerSupported`, `isPageActionsSupported`                                                                                            |
| [Datastreams](https://docs.blynk.io/en/html-widget-developer-guide/datastreams.md)                              | `getValue`, `getValues`, `sendValue`, datastream selectors                                                                                                                                      |
| [Historical & Map Data](https://docs.blynk.io/en/html-widget-developer-guide/historical-and-map-data.md)        | `getHistoricalData`, `getMapData`                                                                                                                                                               |
| [Device](https://docs.blynk.io/en/html-widget-developer-guide/device.md)                                        | `getDeviceInfo`, device image, `getDeviceTags`                                                                                                                                                  |
| [Device Metadata](https://docs.blynk.io/en/html-widget-developer-guide/device-metadata.md)                      | `getAllDeviceMetadata`, `getDeviceMetadata`, `updateDeviceMetadata`                                                                                                                             |
| [Device Files & Assets](https://docs.blynk.io/en/html-widget-developer-guide/device-files-and-assets.md)        | `getDeviceFiles`, `getDeviceFile`, `getDeviceFileBlob`, `uploadDeviceFile`, `deleteDeviceFile`, `getAssets`, `getAsset`, `getAssetBlob`                                                         |
| [Events](https://docs.blynk.io/en/html-widget-developer-guide/events.md)                                        | `getDeviceEventsPermissions`, `getDeviceEvents`, `getDeviceEventComments`, `addDeviceEventComment`, `resolveDeviceEvent`, `archiveDeviceEvent`, `unarchiveDeviceEvent`, `createDeviceEventNote` |
| [Data Engine](https://docs.blynk.io/en/html-widget-developer-guide/data-engine.md)                              | `executeDataEngineQuery`                                                                                                                                                                        |
| [Key-Value Storage](https://docs.blynk.io/en/html-widget-developer-guide/key-value-storage.md)                  | `getStorageItem`, `setStorageItem`, `removeStorageItem`, `clearStorage`                                                                                                                         |
| [User & Organization](https://docs.blynk.io/en/html-widget-developer-guide/user-and-organization.md)            | `isPermissionAllowed`, `getUnitSystems`                                                                                                                                                         |
| [Navigation](https://docs.blynk.io/en/html-widget-developer-guide/navigation.md)                                | `openDeviceInfo`, `openDeviceEvents`, `openAutomations`, `getPages`, `showPage`, `closePage`, `closeAllPages`                                                                                   |
| [Theme & Layout](https://docs.blynk.io/en/html-widget-developer-guide/theme-and-layout.md)                      | `getTheme`, CSS custom properties, container queries                                                                                                                                            |
| [Callbacks](https://docs.blynk.io/en/html-widget-developer-guide/callbacks.md)                                  | `setCallbacks` and the six callbacks                                                                                                                                                            |
| [Errors, Logging & Cleanup](https://docs.blynk.io/en/html-widget-developer-guide/errors-logging-and-cleanup.md) | `BlynkBridgeError`, `sendError`, `setOnErrorEnabled`, `log`, `setLogging`, `destroy`                                                                                                            |
| [Platform Differences](https://docs.blynk.io/en/html-widget-developer-guide/platform-differences.md)            | Web vs. mobile at a glance                                                                                                                                                                      |
| [Tips & Gotchas](https://docs.blynk.io/en/html-widget-developer-guide/tips-and-gotchas.md)                      | Short rules worth remembering                                                                                                                                                                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
