API Reference

Detailed documentation for all hooks and utilities provided by Skybridge.

Skybridge exports hooks and utilities from skybridge/web that work across multiple runtimes. See the compatibility matrix below for platform-specific availability.

State Management

useToolInfo

Get initial tool input, output and metadata

useWidgetState

Persist state across widget renders

Context Sync

data-llm

Sync widget UI state with the model for contextual responses

Utilities

createStore

Create a Zustand store that automatically syncs with widget state

User Interface

useLayout

Get layout and visual environment (theme, safe area)

useUser

Get user information (locale, device type)

useDisplayMode

Get and request widget display mode changes

useRequestModal

Open a modal portaled outside of the widget iframe

Actions

useCallTool

Call tools from within a widget

useOpenExternal

Open external links

useSendFollowUpMessage

Send a follow-up message in the conversation

useFiles

Upload and download files

useSetOpenInAppUrl

Set URL for “open in app” button in fullscreen mode in ChatGPT

Advanced

useAppsSdkContext

Low-level hook to subscribe to window.openai state values (Apps SDK)

useMcpAppContext

Low-level hook to subscribe to MCP App host context (MCP Apps)

Import

All hooks and utilities are exported from skybridge/web:

import {
  createStore,
  useCallTool,
  useDisplayMode,
  useFiles,
  useLayout,
  useSetOpenInAppUrl,
  useAppsSdkContext,
  useMcpAppContext,
  useOpenExternal,
  useRequestModal,
  useSendFollowUpMessage,
  useToolInfo,
  useUser,
  useWidgetState,
} from "skybridge/web";

Runtime Compatibility

Skybridge supports two runtime environments: Apps SDK (ChatGPT) and MCP Apps (open specification). Most hooks work in both, but some features are platform-specific.

Hook / Feature	Apps SDK	MCP Apps	Notes
useToolInfo	✅	✅
useWidgetState	✅	⚠️	MCP Apps: polyfilled; state doesn’t persist across widget renders
data-llm	✅	⚠️	MCP Apps: polyfilled (same limitation as useWidgetState)
useCallTool	✅	✅
useSendFollowUpMessage	✅	✅
useOpenExternal	✅	✅
useLayout	✅	✅
useUser	✅	✅
useDisplayMode	✅	✅
useFiles	✅	❌	Apps SDK only
useSetOpenInAppUrl	✅	❌	Apps SDK only
useRequestModal	✅	⚠️	MCP Apps: polyfilled; renders in iframe instead of host modal
useAppsSdkContext	✅	❌	Apps SDK only
useMcpAppContext	❌	✅	MCP Apps only

Learn more about runtime differences in Write Once, Run Everywhere.