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 }useStoragedefaults to'local'(localStorage, included in community defaults).usePersistentStorageusesIndexedDBand requirescapabilities.storage: ['local', 'persistent'].useSessionStoragerequirescapabilities.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): voidDocument, 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.charCountdoc.appendBlock(type, content?) => string,doc.scrollToBlock(id),doc.scrollToHeading(idOrText)doc.read:getBlock,getChildren,getParent,getRootBlockIds,findBlocksByType,getPageMeta,getSelectiondoc.write(requiresdocument: ['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 | nullSee 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;
}useClipboardcheckscapabilities.clipboard('write', included incommunitydefaults;'external'blocks must declareclipboard: ['write']).useOrbixFileUploaduploads to the workspace Supabase Storage bucket when signed into an authenticated Orbix workspace session, and falls back to a localblob: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
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>
);
}