Build TagoIO Custom Widgets with React. This SDK gives you a set of hooks and a Provider component so you can read device data, send data, and access platform resources using familiar React patterns.

If you're looking for the plain JavaScript version, see @tago-io/custom-widget.

Installation

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

Quick Start

Wrap your app in <TagoIOProvider>, then use hooks to access data:

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

function App() {
  return (
    <TagoIOProvider>
      <Dashboard />
    </TagoIOProvider>
  );
}

function Dashboard() {
  const { widget, isLoading } = useWidget();
  const { records } = useRealtimeData();

  if (isLoading) return <p>Loading...</p>;

  return (
    <div>
      <h1>{widget?.label}</h1>
      <ul>
        {records.map((r) => (
          <li key={r.id}>
            {r.variable}: {r.value}
          </li>
        ))}
      </ul>
    </div>
  );
}

Provider

<TagoIOProvider
  realtimeStrategy="merge" // "replace" | "append" | "merge" (default: "merge")
  realtimeMaxRecords={1000} // max records for "append" strategy
  allowedOrigins={["https://admin.tago.io"]} // optional origin validation
  readyOptions={{ header: { color: "#333" } }}
  dictionary={Dictionary} // optional: Dictionary class from @tago-io/sdk
>
  <App />
</TagoIOProvider>

Hooks

Receiving Data

Hook	Description
`useWidget()`	Widget config, loading state, variables, IDs
`useRealtimeData(options?)`	Realtime data with optional selector for filtering
`useResourceData()`	Platform resources (device list, users, entities) + `refresh()`
`useUserInformation()`	User token, language, runURL
`useBlueprintDevices()`	Blueprint device selections and settings
`useWidgetErrors()`	Error accumulation with clear
`useWidgetData()`	Convenience: combines widget + realtime + errors

Selective Subscriptions

Components only re-render when their specific data slice changes:

// Only re-renders when temperature data changes
const { records } = useRealtimeData({
  selector: (data) => data.filter((d) => d.data?.variable?.includes("temperature")),
});

Mutations

Hook	Description
`useSendData()`	Send data records to devices
`useEditData()`	Edit existing data records
`useDeleteData()`	Delete data records
`useEditResourceData()`	Edit resource-level data

Each returns { mutationFn, isMutating, error, reset }.

const { openLink, closeModal } = useNavigation();

i18n

import { Dictionary } from "@tago-io/sdk";

// In provider:
<TagoIOProvider dictionary={Dictionary}>

// In component:
const { t, tSync, language } = useDictionary();
const translated = await t("Hello");