@huitzo/dashboard-sdk-react

React hooks and components for building Huitzo Dashboards. Wraps the core @huitzo/dashboard-sdk client with React context, command execution hooks, and reusable UI components.

Dashboards always run inside Huitzo Hub — the provider requires a mount context from Hub's mount() call.

Installation

npm install @huitzo/dashboard-sdk @huitzo/dashboard-sdk-react

Quick Start

import type { HuitzoMountContext } from '@huitzo/dashboard-sdk-react';
import { HuitzoProvider } from '@huitzo/dashboard-sdk-react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

export function mount(container: HTMLElement, context: HuitzoMountContext) {
  const root = createRoot(container);
  root.render(
    <HuitzoProvider context={context}>
      <App />
    </HuitzoProvider>
  );
}

Hooks

useHuitzo

Access the client instance and auth state.

Returns: { client, user, isAuthenticated, mountContext, isPackInstalled }

import { useHuitzo } from '@huitzo/dashboard-sdk-react';

function MyComponent() {
  const { client, user, isAuthenticated, mountContext, isPackInstalled } = useHuitzo();
}

useCommand

Execute Intelligence Pack commands with loading/error state.

Returns: { execute, data, loading, error, reset, status, isIdle, isSuccess, isError }

Options: onSuccess, onError, cacheTime, initialArgs

import { useCommand } from '@huitzo/dashboard-sdk-react';

function ProcessClaim() {
  const { execute, data, loading, error } = useCommand<ClaimResult>(
    '@acme/claims/process-claim',
  );

  return (
    <button onClick={() => execute({ claimId: 'CLM-123' })} disabled={loading}>
      {loading ? 'Processing...' : 'Process Claim'}
    </button>
  );
}

useHubContext

Read Hub environment info (theme, user, dashboard slug). Theme is reactive — updates when Hub toggles the theme.

Returns: { hubUrl, dashboardSlug, user, theme }

import { useHubContext } from '@huitzo/dashboard-sdk-react';

function Header() {
  const { dashboardSlug, theme } = useHubContext();
  return <span>Dashboard: {dashboardSlug} ({theme})</span>;
}

useHubNavigation

Programmatic navigation within Hub.

Returns: { navigateToHub, navigateToDashboard, navigateToExplore, navigateToSettings, currentDashboard }

import { useHubNavigation } from '@huitzo/dashboard-sdk-react';

function BackButton() {
  const { navigateToHub, navigateToDashboard } = useHubNavigation();
  return <button onClick={navigateToHub}>Back to Hub</button>;
}

usePacks

Query installed Intelligence Packs.

Returns: { packs, loading, error, isInstalled, refetch }

import { usePacks } from '@huitzo/dashboard-sdk-react';

function PackList() {
  const { packs, loading, error, isInstalled, refetch } = usePacks();

  if (loading) return <p>Loading packs...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {packs.map(pack => (
        <li key={pack.id}>{pack.name} (v{pack.version})</li>
      ))}
    </ul>
  );
}

Stub Hooks (not yet implemented)

These hooks are exported but throw HuitzoError on invocation. They will be implemented when their underlying SDK features are ready.

• useConnectionStatus — Track WebSocket connection status. Will return { status, isConnected, reconnect }.
• useHubActions — Trigger Hub-level UI actions (notifications, dialogs, settings). Will return { showNotification, showConfirmDialog, openSettings }.
• useHubBreadcrumbs — Communicate breadcrumb state to the Hub shell. Accepts BreadcrumbItem[].
• useRealtime — Subscribe to real-time platform events. Accepts (event, callback).

Components

DashboardInfoBlock

Displays a titled info block with optional description, icon, and metadata.

import { DashboardInfoBlock } from '@huitzo/dashboard-sdk-react';

<DashboardInfoBlock
  title="Claims Overview"
  description="Real-time claims processing dashboard"
  icon="📊"
  metadata={[{ label: 'Status', value: 'Active' }]}
/>

DashboardTile

A clickable tile for dashboard navigation or actions. Requires exactly one of onClick or href.

import { DashboardTile } from '@huitzo/dashboard-sdk-react';

<DashboardTile
  name="Process Claims"
  description="Review and process pending claims"
  icon="📋"
  onClick={() => navigate('/claims')}
/>

Design Tokens

Import the CSS tokens for Hub-consistent styling:

@import '@huitzo/dashboard-sdk-react/styles';

Development

npm run build     # Build ESM + CJS + DTS
npm run test      # Run unit tests
npm run lint      # Run biome
npm run dev       # Watch mode

License

MIT