@onaio/akuko-embed-react

React wrapper for @onaio/akuko-embed-sdk. It renders an <AkukoDashboard> component that mounts the SDK into a managed container, wires SDK events to on* callback props, and exposes the imperative methods through a ref.

Install

pnpm add @onaio/akuko-embed-react react react-dom
# or: npm install @onaio/akuko-embed-react react react-dom

react and react-dom (>= 18) are peer dependencies. @onaio/akuko-embed-sdk is bundled as a dependency, so you don't install it separately.

Usage

import { useRef } from "react";
import {
  AkukoDashboard,
  type AkukoDashboardHandle,
} from "@onaio/akuko-embed-react";

export function Analytics() {
  const ref = useRef<AkukoDashboardHandle>(null);

  return (
    <>
      <button onClick={() => ref.current?.refresh()}>Refresh</button>
      <AkukoDashboard
        ref={ref}
        dashboardId="your-dashboard-id"
        baseUrl="https://akuko.io"
        theme={{ primary: "#2563eb", darkMode: false }}
        onReady={() => console.log("ready")}
        onResolved={(r) => console.log("resolved", r.status)}
        onError={(e) => console.error("embed error", e)}
      />
    </>
  );
}

Props

AkukoDashboardProps extends every @onaio/akuko-embed-sdk option except container (the component manages its own mount node) and adds event callbacks:

| Callback | SDK event | |----------|-----------| | onReady | akuko:ready | | onResolved | akuko:resolved (payload typed as ResolveResponse) | | onResize | akuko:resize ({ height }) | | onFilterChange | akuko:filterChange | | onCellClick | akuko:cellClick | | onDashboardChange | akuko:dashboardChange | | onProvisioningStatus | akuko:provisioningStatus | | onLinkProjectsDone | akuko:linkProjectsDone | | onNavigate | akuko:navigate ({ scope, onadataProjectId, ownerUsername? }) | | onShare | akuko:share ({ postId, scope, url? }) | | onClose | akuko:close | | onError | akuko:error |

Pass exactly one entry prop (dashboardId, spaceUuid, onadataOrgId, onadataProjectId, onadataFormId, or linkProjectsOrgId) — see the SDK README for the full option, theme, visibility, and event reference.

theme, visibility, and filters props are reactive: changing them re-pushes the new value into the embedded dashboard. (The visible viewport is reported automatically on scroll/resize.)

Imperative handle

ref exposes AkukoDashboardHandle:

ref.current?.setTheme(theme);
ref.current?.setVisibility(visibility);
ref.current?.setViewport({ top, height }); // usually automatic (reported on scroll/resize)
ref.current?.setFilters(filters);
ref.current?.clearFilters(keys?);     // omit keys to clear all
ref.current?.refresh();
ref.current?.getState();
ref.current?.linkProjects();          // requires onadataOrgId
await ref.current?.resyncMembers({ scope: "org" });
await ref.current?.logout();

The component calls destroy() automatically on unmount.

Reference

See @onaio/akuko-embed-sdk for the complete option, theme, visibility, event, and SSO reference.

License

Apache-2.0