Data and Host State Hooks

This page focuses on runtime hooks most widgets use.

Data Hooks

useStream

Use for subscription style updates from GraphQL streams.

Returns:

  • status (idle, loading, ok, failed)

  • data

  • error

  • retry()

usePolling

Use for interval based refresh logic, usually driven by useWidgetRefreshRate(instanceId).

useMutation

Use for write operations with stable execute semantics.

useStreamHistory

Use when you need a rolling history window from a selector.

Host State Hooks

  • useBrush: read/set global brush expression

  • useVariables: read/set dashboard variable map

  • useHostVariables: read resolved host-level variables (read-only; from the host environment, not dashboard config)

  • useWorkspace: read/set active workspace

  • useUserTimeRange and useEffectiveTimeRange: time selection

  • useWidgetLayout: host layout measurements

  • useThemeMode: light/dark mode awareness

  • useReplayMode: detect whether the dashboard is in replay/offline mode

  • useRoleLevelAccess: read the user’s current role level for conditional rendering or feature gating

  • useWidgetConfigPersistence: persist and restore widget-local state across page reloads (separate from schema config)

Practical Pattern: Live + Polling Fallback

components-table-widget exposes useLiveData in schema and supports both modes:

  • useLiveData = true: stream updates

  • useLiveData = false: polling on dashboard refresh cadence

This gives users control when a backend stream is unavailable or too expensive.

Practical Pattern: Variable + Workspace Interaction

grid-widget integrates click actions with host state:

  • On square click, optionally set a selected variable value

  • Optionally switch workspace

  • Formatting uses INPUT_FORMATED_SCHEMA_TYPE and runtime formatting helpers

Keep this behavior explicit in schema descriptions so users understand side effects.