@emban/react

Native React components for Emban embedded analytics.

Use this package when your product needs widget-level or dashboard-level composition inside your own React layout, without iframe. The package renders charts natively and uses the same signed tenant-scoped token model as the iframe path.

Use @emban/embed-helper when you want the published customer-facing dashboard inside a signed iframe. Use @emban/sdk on the server to create signed sessions.

Install

npm install @emban/react echarts react react-dom

echarts is a peer dependency and must be installed by the host app.

Backend contract

Your backend still creates the signed session with @emban/sdk. The native React path needs:

• host
• token
• dashboardId

import { EmbanClient } from '@emban/sdk'

const client = new EmbanClient({
  baseUrl: 'https://emban.sidelabs.dev',
  apiKey: process.env.EMBAN_ADMIN_KEY!,
})

const session = await client.createEmbedSession({
  tenantId: 'workspace_acme',
  dashboardId: 'dash_123',
  expiresIn: 3600,
})

return {
  host: 'https://emban.sidelabs.dev',
  token: session.token,
  dashboardId: 'dash_123',
}

Quickstart

import {
  EmbanProvider,
  EmbanWidget,
  EmbanDashboard,
  useEmbanRuntime,
} from '@emban/react'

function RefreshButton() {
  const runtime = useEmbanRuntime()
  return <button onClick={() => runtime.refetch()}>Refresh</button>
}

export function Analytics({ session }: {
  session: { host: string; token: string; dashboardId: string }
}) {
  return (
    <EmbanProvider
      host={session.host}
      token={session.token}
      dashboardId={session.dashboardId}
      filters={{ period: '30d' }}
      theme={{ primaryColor: '#0f6a7d' }}
    >
      <div style={{ display: 'grid', gap: 16 }}>
        <EmbanWidget
          widgetId="requests_kpi"
          height={180}
          onDrillEvent={event => {
            console.log(event.widgetId, event.dimension, event.value)
          }}
        />

        <EmbanDashboard
          rowHeight={72}
          onDrillEvent={event => {
            console.log(event.widgetTitle, event.label, event.rawPoint)
          }}
        />

        <RefreshButton />
      </div>
    </EmbanProvider>
  )
}

Standalone widget (no provider)

For isolated widget embeds — a single tile on a landing page, inside a portal, or anywhere you want to skip the provider — pass host and token directly. The token must be widget-scoped (widget_ids) when created with @emban/sdk.

// Backend: mint a widget-scoped token
const session = await client.createEmbedSession({
  tenantId: 'workspace_acme',
  widgetIds: ['w_requests_kpi'],
  expiresIn: 3600,
})

// Frontend: no <EmbanProvider> required
import { EmbanWidget } from '@emban/react'

export function TrafficCard({ host, token }: { host: string; token: string }) {
  return (
    <EmbanWidget
      widgetId="w_requests_kpi"
      host={host}
      token={token}
      height={200}
      theme={{ primaryColor: '#0f6a7d' }}
    />
  )
}

The standalone widget fetches from ${host}/embed/widget/{widgetId}/data, so it works against any widget published from the Widget Library (/app/widgets).

Runtime API

useEmbanRuntime() exposes provider-scoped data loading control:

const runtime = useEmbanRuntime()

await runtime.prefetch()
await runtime.refetch()
runtime.invalidate()

const dashboard = runtime.getSnapshot()
const widget = runtime.getWidgetSnapshot('requests_kpi')

Public API

Exports:

• EmbanProvider
• EmbanWidget
• EmbanDashboard
• useEmbanRuntime
• useWidgetData
• useAllWidgetsData
• EmbanProviderProps
• EmbanWidgetProps
• EmbanDashboardProps
• EmbanTheme
• EmbanFilters
• EmbanRuntime
• EmbanDrillEvent
• EmbanWidgetsSnapshot
• EmbanWidgetSnapshot
• WidgetConfig
• WidgetLayout
• WidgetDataResponse
• ThemeVars

Interaction model

• Provider-level cache deduplicates dashboard fetches for sibling widgets.
• Theme state is provider-local, so multiple EmbanProvider instances can coexist on one page.
• onDrillEvent carries richer context than the legacy onDrill(dimension, value) callback:
  • dashboardId
  • widgetId
  • widgetTitle
  • kind
  • chartType
  • dimension
  • value
  • label
  • filters
  • rawPoint

Notes

• This package is React-only and intended for native composition.
• It does not replace the signed session model; tenant isolation still stays server-side.
• The current renderer surface covers native KPI, list, table, and ECharts-backed widgets.
• If you only need the published dashboard inside your app, prefer @emban/embed-helper.