Skip to main content
The useAppsSdkContext hook is a low-level hook that subscribes to global state values exposed by the OpenAI host. This hook powers many of the other Skybridge hooks and can be used directly when you need access to specific global values.
For most use cases, prefer using the specialized hooks like useLayout, useUser, useDisplayMode, etc., as they provide a more convenient API.

​
Basic usage

import { useAppsSdkContext } from "skybridge/web";

function ThemeDisplay() {
  const theme = useAppsSdkContext("theme");

  return <p>Current theme: {theme}</p>;
}

​
Parameters

​
key

key: keyof AppsSdkContext
Required The key of the global value to subscribe to. Available keys include:
KeyTypeDescription
theme"light" | "dark"The current color theme
localestringThe user’s locale (e.g., "en-US")
displayMode"inline" | "fullscreen" | "pip"The widget’s display mode
userAgentUserAgentDevice and capability information
maxHeightnumberMaximum height available for the widget
safeAreaSafeAreaSafe area insets for the widget
toolInputobjectThe input arguments passed to the tool
toolOutputobject | nullThe tool’s output (when available)
toolResponseMetadataobject | nullAdditional metadata from the tool response
widgetStateobject | nullThe persisted widget state

​
Returns

value: AppsSdkContext[K] | undefined
The current value of the specified global, or undefined if not available.

​
Examples

​
Reading Safe Area Insets

import { useAppsSdkContext } from "skybridge/web";

function SafeAreaAwareWidget() {
  const safeArea = useAppsSdkContext("safeArea");

  if (!safeArea) {
    return <div>Loading...</div>;
  }

  return (
    <div
      style={{
        paddingTop: safeArea.insets.top,
        paddingBottom: safeArea.insets.bottom,
        paddingLeft: safeArea.insets.left,
        paddingRight: safeArea.insets.right,
      }}
    >
      <p>Content with safe area padding</p>
    </div>
  );
}

​
Respecting Max Height

import { useAppsSdkContext } from "skybridge/web";

function ScrollableContent() {
  const maxHeight = useAppsSdkContext("maxHeight");

  return (
    <div
      style={{
        maxHeight: maxHeight ? `${maxHeight}px` : "auto",
        overflow: "auto",
      }}
    >
      {/* Scrollable content */}
    </div>
  );
}

​
Accessing Tool Input

import { useAppsSdkContext } from "skybridge/web";

function ToolInputDisplay() {
  const toolInput = useAppsSdkContext("toolInput");

  return (
    <div>
      <h3>Tool Input:</h3>
      <pre>{JSON.stringify(toolInput, null, 2)}</pre>
    </div>
  );
}

​
Multiple Globals

import { useAppsSdkContext } from "skybridge/web";

function EnvironmentInfo() {
  const theme = useAppsSdkContext("theme");
  const locale = useAppsSdkContext("locale");
  const displayMode = useAppsSdkContext("displayMode");
  const userAgent = useAppsSdkContext("userAgent");

  return (
    <div>
      <h3>Environment</h3>
      <ul>
        <li>Theme: {theme}</li>
        <li>Locale: {locale}</li>
        <li>Display Mode: {displayMode}</li>
        <li>Device: {userAgent?.device.type}</li>
        <li>Touch: {userAgent?.capabilities.touch ? "Yes" : "No"}</li>
        <li>Hover: {userAgent?.capabilities.hover ? "Yes" : "No"}</li>
      </ul>
    </div>
  );
}

​
Type Reference

​
AppsSdkContext

type AppsSdkContext = {
  theme: "light" | "dark";
  userAgent: UserAgent;
  locale: string;
  maxHeight: number;
  displayMode: "inline" | "fullscreen" | "pip";
  safeArea: SafeArea;
  toolInput: Record<string, unknown>;
  toolOutput: Record<string, unknown> | { text: string } | null;
  toolResponseMetadata: Record<string, unknown> | null;
  widgetState: Record<string, unknown> | null;
};

​
UserAgent

type UserAgent = {
  device: { type: "mobile" | "tablet" | "desktop" | "unknown" };
  capabilities: {
    hover: boolean;
    touch: boolean;
  };
};

​
SafeArea

type SafeArea = {
  insets: {
    top: number;
    bottom: number;
    left: number;
    right: number;
  };
};