Skip to Content

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 useDashboardData and DashboardData, your app uses React 18 or 19.

Steps

  1. Install the package:

    npm install @databrainhq/plugin
  2. Import from the data subpath 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

ExportUse 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

OptionTypeDefaultWhat it does
tokenstringrequiredThe guest token. With no token, the hook stays idle.
dashboardIdstringnoneThe dashboard id. Leave it out only when the guest token names one dashboard.
configIdstringnoneData app configuration id.
isEnbooleannoneAsks for the English response.
baseUrlstringhttps://api.usedatabrain.comBackend origin, for example a self-hosted one.
enabledbooleantruefalse 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

FieldTypeWhat it holds
dataobject or nullThe /api/v2/dashboard response.
data.externalDashboardobjectThe dashboard. Typed fields id, externalDashboardId and name; other fields can be present.
data.externalMetricsarrayThe metric definitions. Typed fields id and name; other fields can be present.
statusstringidle, loading, success or error.
isLoadingbooleantrue while status is loading.
errorDashboardDataError or nullmessage, 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:

HeaderValue
X-Plugin-TokenThe guest token. It is never put in the URL.
X-Plugin-OriginYour page’s host.
X-Dbn-Plugin-VersionThe plugin build.
X-Dbn-Plugin-ContractThe plugin contract number.

If you send requests through your own proxy, let all four headers through.

If something goes wrong

  • error.status is 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. baseUrl does not point at a Databrain backend.

Next: Embed a dashboard.