Custom Widget SDK 2.0: React Support

General Announcements
1

The Custom Widget SDK now has a React package. The new @tago-io/custom-widget-react gives you a hooks-based API for building dashboard widgets — real-time data, CRUD operations, widget config, all accessible through hooks.

npm install @tago-io/custom-widget-react

Requires React 18+. Full TypeScript support included.

How it works

Wrap your app in <TagoIOProvider>. After that, every hook has access to the widget context — no manual listener setup, no postMessage wiring.

import { createRoot } from "react-dom/client";
import { TagoIOProvider, useRealtimeData, useWidget } from "@tago-io/custom-widget-react";

function WidgetContent() {
  const { label, loading } = useWidget();
  const { data, eventCount } = useRealtimeData();

  if (loading) {
    return <p>Loading...</p>;
  }

  return (
    <div>
      <h3>{label}</h3>
      <p>{data.length} records — {eventCount} updates received</p>
    </div>
  );
}

createRoot(document.getElementById("root")!).render(
  <TagoIOProvider>
    <WidgetContent />
  </TagoIOProvider>
);

The hooks

14 hooks covering the full widget lifecycle:

  • useRealtimeData() — Subscribe to live device data. Supports three strategies for incoming records: replace, append, or merge.
  • useSendData(), useEditData(), useDeleteData() — CRUD operations on device data. Loading and error states come back from the hook directly.
  • useWidget() — Widget config, variables, and dashboard context.
  • useUserInformation() — Current language, timezone, token, and user preferences.
  • useBlueprintDevices() — Blueprint device selections and settings.

Re-renders

The SDK uses selective subscriptions — components only re-render when the specific data they consume changes. The merge strategy applies structural sharing, so unchanged records keep their references. If you’ve dealt with unnecessary re-renders from context providers before, this is specifically designed to avoid that.

Vanilla JS still works

The vanilla SDK (@tago-io/custom-widget) is at v2.0.1 and fully supported. Existing widgets don’t need to change.

Check the examples in the repo for read-data, send-data, and resource-access patterns.