Skip to Content
OrbixDocs
Block SDK · Reference

Hooks

TypeScript signatures, options, and return values for hooks across @orbixdocs/sdk, /ai, and /realtime.

All hooks below must be called inside a mounted Orbix block (OrbixBlockInstanceContext). Calling an SDK hook outside a block logs a console error and no-ops unless enableStandaloneBlockHarness(true) was called first.

State and scope (@orbixdocs/sdk)

useOrbixState

function useOrbixState<T>(
  props: BlockRenderProps,
  defaultValue: T,
  options?: StateOptions
): [T, StateSetter<T>, StateControls<T>];

function useOrbixState<T>(
  props: BlockRenderProps,
  key: string,
  defaultValue: T,
  options?: StateOptions
): [T, StateSetter<T>, StateControls<T>];

function useOrbixState<T>(
  key: string,
  defaultValue: T,
  options?: StateOptions
): [T, StateSetter<T>, StateControls<T>];

Prop

Type

controls contains { state, setState, reset, undo, redo, canUndo, canRedo, scope }. See Store and sync state.

Scoped convenience hooks

usePersonalState<T>(key: string, defaultValue: T, opts?: { memberKey?: string }): [T, (next: T | ((prev: T) => T)) => void, { scope: 'personal'; member: any; isSimulating: boolean; reset: () => void }]
useTeamState<T>(key: string, defaultValue: T, opts?: { workspaceWide?: boolean; teamKey?: string }): [T, (next: T | ((prev: T) => T)) => void, { scope: 'team'; workspaceWide: boolean; reset: () => void }]
useMemberState<T>(key: string, defaultValue: T): { myValue: T; setMyValue: (v: T | ((prev: T) => T)) => void; clearMyValue: () => void; hasSubmitted: boolean; entries: any[]; byMember: Record<string, T>; values: T[]; count: number; activeMember: any }
useVoting(pollKey?: string, config?: { question?: string; subtitle?: string; options?: Array<string | { id: string; label: string; description?: string }>; allowMultiple?: boolean; anonymous?: boolean; isClosed?: boolean }): { question: string; results: Array<{ id: string; label: string; count: number; percentage: number; voters: any[]; isVotedByMe: boolean; isLeading: boolean }>; myVotes: string[]; vote: (optionId: string) => void; toggleVote: (optionId: string) => void; clearMyVote: () => void; totalVotes: number; totalVoters: number; isClosed: boolean }

Device storage (@orbixdocs/sdk)

useStorage<T>(key: string, defaultValue: T, opts?: { scope?: 'local' | 'personal' | 'team'; workspaceWide?: boolean }): [T, (v: T) => Promise<void>, { loading: boolean; reset: () => Promise<void>; scope: string }]
usePersistentStorage<T>(key: string, defaultValue: T): [T, (v: T) => Promise<void>, boolean]
useSessionStorage<T>(key: string, defaultValue: T): [T, (v: T) => void]
useCache(): { get: <T>(key: string, fallback?: T) => T | undefined; set: (key: string, value: unknown, ttlSeconds?: number) => void }
  • useStorage defaults to 'local' (localStorage, included in community defaults).
  • usePersistentStorage uses IndexedDB and requires capabilities.storage: ['local', 'persistent'].
  • useSessionStorage requires capabilities.storage: ['local', 'session'].

Block graph ports and events (@orbixdocs/sdk)

useBlockInput<T>(port: string, defaultValue?: T, opts?: { sourceBlockId?: string; sourcePort?: string }): T
useBlockOutput<T>(port: string, value?: T, opts?: { label?: string; description?: string; type?: PortDataType; isPublic?: boolean }): (next: T, opts?: any) => void
useBlockOutputs(outputs: Record<string, unknown>, metadata?: Record<string, any>): void
useBlockEvent<T = any>(eventName: string, handler: (payload: T) => void): void
emitBlockEvent(eventName: string, payload?: unknown, explicitBlockId?: string): void

See Connect blocks together.

Document, workspace, and database (@orbixdocs/sdk)

useOrbixDocument(): OrbixDocumentFacade
useOrbixWorkspace(): OrbixWorkspaceFacade
useOrbixDatabase(): { current: () => any; connected: (databaseId: string) => any; workspace: () => { listDatabases: () => any[]; createDatabase: (name: string, schema?: any) => any } }
useLiveQuery<T extends { id?: string }>(table: string, opts?: { filter?: (row: T) => boolean; sort?: (a: T, b: T) => number; limit?: number; initialData?: T[]; scope?: 'block' | 'workspace' }): { data: T[]; loading: boolean; error: Error | null; insert: (item: T) => Promise<T>; update: (id: string, patch: Partial<T>) => Promise<void>; remove: (id: string) => Promise<void>; refetch: () => void }

All methods on useOrbixDocument() and useOrbixWorkspace() are synchronous:

  • doc.pageId, doc.pageTitle, doc.blockCount, doc.headings, doc.blocks, doc.wikilinks, doc.subpages, doc.wordCount, doc.charCount
  • doc.appendBlock(type, content?) => string, doc.scrollToBlock(id), doc.scrollToHeading(idOrText)
  • doc.read: getBlock, getChildren, getParent, getRootBlockIds, findBlocksByType, getPageMeta, getSelection
  • doc.write (requires document: ['read', 'write']): insertBlock(targetId, 'top' | 'bottom' | 'inside', block) => string, updateBlock, deleteBlock, moveBlock, batch(ops), createSubPage(title, blocks?) => string

See Read and edit the document.

Surface, theme, identity, and role permissions (@orbixdocs/sdk)

useOrbixSurface(): {
  surface: 'block' | 'sidebar_panel' | 'fullpage';
  isSplitView: boolean;
  isGlobalView: boolean;
  isInlineBlock: boolean;
  activeDocumentId: string | null;
  dimensions?: { width: number; height: number };
}

useOrbixTheme(): {
  theme: string;
  resolvedMode: 'dark' | 'light';
  themeId: string;
  isDark: boolean;
  isLight: boolean;
  accent: string;
  tokens: { bg: string; card: string; cardHover: string; subtle: string; border: string; text: string; textMuted: string; accent: string };
}

useOrbixUser(): {
  id: string;
  key: string;
  name: string;
  email: string;
  avatarUrl?: string;
  color: string;
  role: string;
  isCurrentUser: boolean;
  authenticatedUser: OrbixCollaboratorProfile;
  collaborators: OrbixCollaboratorProfile[];
  members: OrbixCollaboratorProfile[];
  switchPerspective: (memberIdOrKey: string | null) => void;
  resetPerspective: () => void;
}

useBlockPermissions(props?: BlockRenderProps): {
  currentRole: BlockRole;
  allRoles: BlockRole[];
  isHost: boolean;
  isAdmin: boolean;
  isReadOnly: boolean;
  hasPermission: (permission: BlockPermission | BlockPermission[]) => boolean;
  hasRole: (roleId: string | string[]) => boolean;
  assignRole: (userId: string, roleId: string) => void;
  simulateRole: (roleId: string | null) => void;
}

useBlockId(hookName?: string, explicitId?: string): string
useOrbixBlockInstance(): OrbixBlockInstanceContextValue | null

See Build multi-surface blocks, Match the Orbix theme, and Users and role permissions.

Network and environment (@orbixdocs/sdk)

useOrbixFetch<T = any>(url: string, opts?: RequestInit & { cacheTtl?: number; pollInterval?: number; deps?: unknown[]; lazy?: boolean; proxyUrl?: string }): { data: T | null; loading: boolean; error: string | null; refetch: () => void; lastFetchedAt: number | null }
useOrbixRequest<T = any>(url: string, opts?: RequestInit): { data: T | null; loading: boolean; error: string | null; execute: (body?: unknown, headers?: Record<string, string>) => Promise<T | null> }
orbixFetch(url: string, init?: RequestInit & { blockId?: string; proxyUrl?: string }): Promise<Response>
useOrbixEnv(props?: BlockRenderProps): { env: Record<string, string>; getEnv: (key: string, fallback?: string) => string; setEnv: (key: string, value: string) => void; deleteEnv: (key: string) => void } & Record<string, any>

See Fetch external APIs and Store API keys and secrets.

Canvas, animation, workers, files, and clipboard (@orbixdocs/sdk)

useOrbixCanvas(options?: {
  contextType?: '2d' | 'webgl' | 'webgl2' | 'unmanaged';
  pixelRatio?: boolean;
  glAttributes?: WebGLContextAttributes;
  onResize?: (info: { canvas: HTMLCanvasElement; width: number; height: number; dpr: number }) => void;
}): {
  canvasRef: RefObject<HTMLCanvasElement>;
  width: number;
  height: number;
  physicalWidth: number;
  physicalHeight: number;
  dpr: number;
  ready: boolean;
}

useOrbixAnimationLoop(
  callback: (deltaMs: number, elapsedMs: number) => void,
  options?: {
    fps?: number;
    pauseWhenHidden?: boolean;
    autoStart?: boolean;
    visibilityTarget?: RefObject<Element | null>;
    onError?: (error: unknown) => void;
  }
): {
  start: () => void;
  stop: () => void;
  isRunning: boolean;
  fps: number;
}

useWorker<TInput = any, TOutput = any>(
  workerFnOrCode: ((input: TInput) => TOutput | Promise<TOutput>) | string
): {
  run: (input: TInput) => Promise<TOutput>;
  terminate: () => void;
}

useOrbixWorker<TInput = any, TResult = any>(
  workerFnOrUrl: string | ((e: MessageEvent) => void),
  options?: {
    onMessage?: (result: TResult) => void;
    onError?: (err: ErrorEvent) => void;
    timeout?: number;
  }
): {
  postMessage: (data: TInput) => void;
  terminate: () => void;
  isBusy: boolean;
  lastResult: TResult | null;
  error: Error | null;
}

useOrbixFileUpload(options?: {
  bucket?: string;
  onSuccess?: (result: UploadResult) => void;
  onError?: (err: Error) => void;
}): {
  upload: (file: File) => Promise<UploadResult | null>;
  isUploading: boolean;
  progress: number;
  lastResult: UploadResult | null;
  error: Error | null;
}

useClipboard(timeoutMs?: number): {
  copy: (text: string) => Promise<boolean>;
  copied: boolean;
  error: Error | null;
}
  • useClipboard checks capabilities.clipboard ('write', included in community defaults; 'external' blocks must declare clipboard: ['write']).
  • useOrbixFileUpload uploads to the workspace Supabase Storage bucket when signed into an authenticated Orbix workspace session, and falls back to a local blob: object URL in offline or standalone mock-host environments.

See Canvas, animation, and workers.

AI (@orbixdocs/sdk/ai)

useOrbixAI(opts?: { systemPrompt?: string; model?: string; temperature?: number }): {
  stream: (optionsOrPrompt: AIStreamOptions | string, onChunk?: (chunk: string, fullText: string) => void) => Promise<string>;
  generate: <T = any>(optionsOrPrompt: AIGenerateOptions | string, extraOptions?: Omit<AIGenerateOptions, 'prompt'>) => Promise<T>;
  generateText: (optionsOrPrompt: AIGenerateOptions | string, extraOptions?: Omit<AIGenerateOptions, 'prompt'>) => Promise<string>;
  cancel: () => void;
  isGenerating: boolean;
  error: Error | null;
  getApiKey: () => string;
  setApiKey: (key: string) => void;
}

See Add AI to a block.

Realtime (@orbixdocs/sdk/realtime)

useCollaborative<T>(
  channelKey: string,
  initialValue: T,
  opts?: {
    peerName?: string;
    peerColor?: string;
    heartbeatIntervalMs?: number;
    onRemoteAction?: (action: string, payload: unknown, senderId: string) => void;
    persist?: boolean;
    pageId?: string;
  }
): {
  state: T;
  setState: (next: T | ((prev: T) => T)) => void;
  peers: Array<{ id: string; name: string; color: string; cursor?: { x: number; y: number }; lastActive: number }>;
  updatePresence: (presence: { cursor?: { x: number; y: number }; name?: string }) => void;
  broadcastAction: (action: string, payload?: unknown) => void;
  isConnected: boolean;
}

useOrbixWebSocket<TIn = any, TOut = any>(
  url: string,
  options?: {
    protocols?: string | string[];
    reconnect?: boolean;
    reconnectDelayMs?: number;
    maxReconnectDelayMs?: number;
    maxRetries?: number;
    maxMessages?: number;
    lazy?: boolean;
  },
  capabilities?: BlockCapabilities
): {
  messages: TIn[];
  lastMessage: TIn | null;
  status: 'idle' | 'connecting' | 'open' | 'closing' | 'closed' | 'error';
  retries: number;
  send: (data: TOut | string) => void;
  disconnect: () => void;
  connect: () => void;
  error: string | null;
}

realtimeEngine.broadcast<T = any>(channelName: string, blockId?: string): BroadcastChannelHandle<T>
realtimeEngine.connectPeer<T = any>(options: P2PConnectionOptions): Promise<P2PDataChannel<T>>
realtimeEngine.sse<T = any>(url: string, blockId?: string): SSEHandle<T>

Realtime transport scopes

useCollaborative syncs state and presence over the browser's BroadcastChannel API across tabs and block instances within the same browser. For cross-user document persistence, use useOrbixState; for cross-user WebRTC data channels signaled over Supabase, use realtimeEngine.connectPeer(...).

Verified hook import check

src/verify-hooks.tsx
import {
  useOrbixState,
  useBlockId,
  useOrbixTheme,
  useOrbixDocument,
  useOrbixSurface,
  useOrbixUser,
  useBlockPermissions,
  useOrbixCanvas,
  useOrbixAnimationLoop,
  useWorker,
  useOrbixWorker,
  useOrbixFileUpload,
  useClipboard,
} from '@orbixdocs/sdk';
import { useOrbixAI } from '@orbixdocs/sdk/ai';
import { useCollaborative, useOrbixWebSocket } from '@orbixdocs/sdk/realtime';

export function HookProbe() {
  const blockId = useBlockId();
  const { isDark } = useOrbixTheme();
  const doc = useOrbixDocument();
  const surface = useOrbixSurface();
  const user = useOrbixUser();
  const perms = useBlockPermissions();
  const canvas = useOrbixCanvas();
  const loop = useOrbixAnimationLoop(() => {}, { autoStart: false });
  const rpcWorker = useWorker((n: number) => n * 2);
  const worker = useOrbixWorker((e: MessageEvent) => {
    self.postMessage(e.data);
  });
  const uploader = useOrbixFileUpload();
  const clipboard = useClipboard();
  const [count] = useOrbixState<number>('count', 0);
  const ai = useOrbixAI();
  const collab = useCollaborative('room', { ready: true });
  const ws = useOrbixWebSocket('wss://example.com/stream', { lazy: true });

  return (
    <div>
      {blockId} · {String(isDark)} · {doc.pageTitle} · {surface.surface} ·{' '}
      {user.name} · {perms.currentRole.id} · {String(canvas.ready)} ·{' '}
      {loop.fps} · {String(typeof rpcWorker.run)} · {String(worker.isBusy)} ·{' '}
      {String(uploader.isUploading)} · {String(clipboard.copied)} · {count} ·{' '}
      {String(ai.isGenerating)} · {collab.peers.length} · {ws.status}
    </div>
  );
}

On this page