Component Options
Load dashboard data without the UI
Get a dashboard's details and metric list with a guest token, and draw them with your own React components.
@databrainhq/plugin/data loads a dashboard’s details and its metric definitions. It draws nothing and does not load the Databrain chart engine.
Before you start
- You have a guest token from your backend. See Guest token body.
- You have the dashboard id from the Embeds page.
- Your page’s domain is in the data app’s whitelisted domains. See Whitelist domains.
- For
useDashboardDataandDashboardData, your app uses React 18 or 19.
Steps
-
Install the package:
npm install @databrainhq/plugin -
Import from the
datasubpath and call the hook:import { useDashboardData } from '@databrainhq/plugin/data'; export function MetricNames({ token, dashboardId }) { const { data, error, isLoading } = useDashboardData({ token, dashboardId }); if (isLoading) return <p>Loading</p>; if (error) return <p>{error.message}</p>; return ( <ul> {(data?.externalMetrics ?? []).map((metric) => ( <li key={metric.id}>{metric.name}</li> ))} </ul> ); }
You see the dashboard’s metric names in your own component.
The three exports
| Export | Use it for |
|---|---|
useDashboardData(options) | A React hook. Returns { data, error, status, isLoading, refetch }. |
<DashboardData {...options}>{(result) => ...}</DashboardData> | The same result as a render prop. |
fetchDashboardData(options) | A plain promise, for code outside React. Takes an optional signal (AbortSignal). |
Options
| Option | Type | Default | What it does |
|---|---|---|---|
token | string | required | The guest token. With no token, the hook stays idle. |
dashboardId | string | none | The dashboard id. Leave it out only when the guest token names one dashboard. |
configId | string | none | Data app configuration id. |
isEn | boolean | none | Asks for the English response. |
baseUrl | string | https://api.usedatabrain.com | Backend origin, for example a self-hosted one. |
enabled | boolean | true | false keeps the hook idle. Hook and component only. |
The hook loads again when an option changes, and cancels the old request. refetch() loads again with the same options.
What you get back
| Field | Type | What it holds |
|---|---|---|
data | object or null | The /api/v2/dashboard response. |
data.externalDashboard | object | The dashboard. Typed fields id, externalDashboardId and name; other fields can be present. |
data.externalMetrics | array | The metric definitions. Typed fields id and name; other fields can be present. |
status | string | idle, loading, success or error. |
isLoading | boolean | true while status is loading. |
error | DashboardDataError or null | message, status (HTTP status) and code from the server. |
The response holds metric definitions, not query results. To show the numbers, use <dbn-dashboard> or <dbn-metric>.
How the request is sent
GET <baseUrl>/api/v2/dashboard?dashboardId=<id> with these headers:
| Header | Value |
|---|---|
X-Plugin-Token | The guest token. It is never put in the URL. |
X-Plugin-Origin | Your page’s host. |
X-Dbn-Plugin-Version | The plugin build. |
X-Dbn-Plugin-Contract | The plugin contract number. |
If you send requests through your own proxy, let all four headers through.
If something goes wrong
error.statusis 401 or 403. The guest token is expired or wrong, or your page’s domain is not whitelisted. Create a new token, then check the whitelisted domains.Databrain returned an invalid response.baseUrldoes not point at a Databrain backend.
Next: Embed a dashboard.