Hooks

React hooks that connect your components to live device data. All hooks require your app to be wrapped in RelayProvider.

useRelayApp()

Access the raw App SDK instance.

import { useRelayApp } from "@relay-x/ui";

const app = useRelayApp(); // RelayAppInstance | null

useRelayConnection()

Access the App SDK instance and connection status.

import { useRelayConnection } from "@relay-x/ui";

const { app, isConnected, error } = useRelayConnection();

Return	Type	Description
app	object | null	The App SDK instance
isConnected	boolean	Whether the SDK is connected
error	string | null	Error message if connection failed (e.g., auth_failed)

useRelayTimeSeries()

Stream historical and/or real-time telemetry data for a device.

import { useRelayTimeSeries } from "@relay-x/ui";

const { data, isLoading, error } = useRelayTimeSeries({
  deviceIdent: "sensor_01",
  metrics: ["temperature", "humidity"],
  mode: "both",
  timeRange: {
    start: Date.now() - 3600000,
    end: Date.now(),
  },
});

Options

Option	Type	Description
deviceIdent	string	The device identifier
metrics	string[]	Metrics to subscribe to
mode	string	"historical", "realtime", or "both"
timeRange	object	{ start: number, end: number } — timestamps in ms
maxPoints	number	(optional) Maximum data points to keep. Default: 10000

Modes

Mode	Behavior
"historical"	Fetches data once for the given time range. No live updates.
"realtime"	Streams live data only. No historical data.
"both"	Fetches historical data first, then streams live updates. New data is merged in.

Return

Return	Type	Description
data	DataPoint[]	Array of data points with merged metrics
isLoading	boolean	true while fetching historical data
error	Error | null	Error if the fetch or stream failed

useRelayLatest()

Get the most recent value for a single metric. Fetches the latest and subscribes to live updates. Returns a RelayDataPoint that can be passed directly to any component's data prop.

import { useRelayLatest } from "@relay-x/ui";

const latest = useRelayLatest({
  deviceIdent: "sensor_01",
  metric: "temperature",
  timeRange: {
    start: Date.now() - 86400000,
    end: Date.now(),
  },
});

// Pass directly to a component
<NeedleGauge data={latest} min={0} max={100} />

Options

Option	Type	Description
deviceIdent	string	The device identifier
metric	string	The metric name
timeRange	object	{ start: number, end: number } — timestamps in ms

Return (RelayDataPoint)

Return	Type	Description
value	number | null	The latest metric value
timestamp	number | null	When the value was recorded (ms)
isLoading	boolean	true while fetching
error	Error | null	Error if the fetch or stream failed

Components that accept a data prop (NeedleGauge, ArcGauge, ProgressBar, StatCard, StatCardWithGraph) expect this exact shape.

useRelayPresence()

Track whether a device is online or offline.

import { useRelayPresence } from "@relay-x/ui";

const { online, lastEvent, isLoading, error } = useRelayPresence("sensor_01");

Return

Return	Type	Description
online	boolean | null	true if online, false if offline, null if unknown
lastEvent	object | null	Last presence event with device_ident and event type
isLoading	boolean	true while initial presence is being determined
error	Error | null	Error if the presence subscription failed