Skip to content
Stratum Docs

@stratum-hq/react

@stratum-hq/react provides a React context provider and pre-built components for tenant switching, hierarchy visualization, and config/permission editing.

Installation

Terminal window
npm install @stratum-hq/react @stratum-hq/core react react-dom

Provider

Wrap your application in StratumProvider to enable all components and hooks:

import { StratumProvider } from "@stratum-hq/react";


function App() {
  return (
    <StratumProvider
      controlPlaneUrl="http://localhost:3001"
      apiKey="sk_live_your_key"
      initialTenantId="optional-default-tenant"
    >
      <YourApp />
    </StratumProvider>
  );
}

The provider creates a StratumClient internally and manages the current tenant state.

useStratum Hook

Access the current tenant context from any child component:

import { useStratum } from "@stratum-hq/react";


function Dashboard() {
  const {
    currentTenant,   // TenantNode | null
    tenantContext,    // TenantContext | null
    loading,         // boolean
    error,           // Error | null
    switchTenant,    // (id: string) => Promise<void>
    apiCall,         // <T>(path, options?) => Promise<T>
  } = useStratum();


  if (loading) return <div>Loading...</div>;
  if (!currentTenant) return <div>Select a tenant</div>;


  return (
    <div>
      <h1>{currentTenant.name}</h1>
      <p>Depth: {currentTenant.depth}</p>
      <p>Strategy: {tenantContext?.isolation_strategy}</p>
      <pre>{JSON.stringify(tenantContext?.resolved_config, null, 2)}</pre>
    </div>
  );
}

Components

TenantSwitcher

Dropdown to select the active tenant:

import { TenantSwitcher } from "@stratum-hq/react";


function Header() {
  return (
    <nav>
      <TenantSwitcher />
    </nav>
  );
}

Automatically fetches the tenant list from the control plane and calls switchTenant() on selection. Displays the current tenant name and a dropdown with all available tenants.

TenantTree

Hierarchical tree view of the tenant structure:

import { TenantTree } from "@stratum-hq/react";


function Sidebar() {
  return <TenantTree />;
}

Displays the full tenant hierarchy with expandable nodes. Clicking a tenant switches to it. Nodes show:

  • Tenant name and slug
  • Depth indicator
  • Active/archived status
  • Child count

ConfigEditor

Editor for tenant configuration key-value pairs:

import { ConfigEditor } from "@stratum-hq/react";


function ConfigPage() {
  return <ConfigEditor />;
}

Displays the resolved config for the current tenant with:

  • Key-value editing with type-appropriate inputs
  • Lock status indicators (locked keys are read-only)
  • Inheritance source information (which ancestor set each value)
  • Add, update, and delete operations

PermissionEditor

Editor for tenant permission policies:

import { PermissionEditor } from "@stratum-hq/react";


function PermissionsPage() {
  return <PermissionEditor />;
}

Displays resolved permissions with:

  • Mode selection (LOCKED / INHERITED / DELEGATED)
  • Revocation mode selection (CASCADE / SOFT / PERMANENT)
  • Source tenant tracking
  • Add, update, and delete operations

apiCall Helper

The apiCall function from the context is a convenience wrapper that automatically adds authentication headers:

const { apiCall } = useStratum();


// GET request
const tenants = await apiCall<TenantNode[]>("/api/v1/tenants");


// POST request
const newTenant = await apiCall<TenantNode>("/api/v1/tenants", {
  method: "POST",
  body: JSON.stringify({
    name: "New Tenant",
    slug: "new_tenant",
  }),
});

Full Example

import {
  StratumProvider,
  useStratum,
  TenantSwitcher,
  TenantTree,
  ConfigEditor,
  PermissionEditor,
} from "@stratum-hq/react";


function App() {
  return (
    <StratumProvider
      controlPlaneUrl="http://localhost:3001"
      apiKey="sk_live_your_key"
    >
      <Layout />
    </StratumProvider>
  );
}


function Layout() {
  const { currentTenant, loading } = useStratum();


  return (
    <div style={{ display: "flex" }}>
      <aside style={{ width: 240 }}>
        <TenantSwitcher />
        <TenantTree />
      </aside>
      <main style={{ flex: 1, padding: 24 }}>
        {loading ? (
          <p>Loading...</p>
        ) : !currentTenant ? (
          <p>Select a tenant from the sidebar.</p>
        ) : (
          <>
            <h1>{currentTenant.name}</h1>
            <h2>Configuration</h2>
            <ConfigEditor />
            <h2>Permissions</h2>
            <PermissionEditor />
          </>
        )}
      </main>
    </div>
  );
}

Scaffolding

Use the CLI to generate React integration boilerplate:

Terminal window
npx @stratum-hq/cli scaffold react --out src/components

This generates:

  • stratum-provider.tsx — AppStratumProvider wrapper with your config
  • tenant-guard.tsx — PermissionGuard and ConfigGuard components
  • use-tenant.ts — usePermission(), useConfig(), useIsRootTenant() hooks