useAppsSdkContext

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 frac hooks and can be used directly when you need access to specific global values.

Tip

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 "@usefractal/frac/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:

Key	Type	Description
theme	"light" | "dark"	The current color theme
locale	string	The user’s locale (e.g., "en-US")
displayMode	"inline" | "fullscreen" | "pip"	The view’s display mode
userAgent	UserAgent	Device and capability information
maxHeight	number | undefined	Maximum height available for the view (if provided by host)
safeArea	SafeArea	Safe area insets for the view
toolInput	object	The input arguments passed to the tool
toolOutput	object | null	The tool’s output (when available)
toolResponseMetadata	object | null	Additional metadata from the tool response
viewState	object | null	The persisted view state
view	{ mode: "inline" | "fullscreen" | "pip"; params?: Record<string, unknown> }	Current view state, including modal params

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 "@usefractal/frac/web";

function SafeAreaAwareView() {
  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 "@usefractal/frac/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 "@usefractal/frac/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 "@usefractal/frac/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 | undefined;
  displayMode: "inline" | "fullscreen" | "pip" | "modal";
  safeArea: SafeArea;
  toolInput: Record<string, unknown>;
  toolOutput: Record<string, unknown> | { text: string } | null;
  toolResponseMetadata: Record<string, unknown> | null;
  widgetState: Record<string, unknown> | null;
  view: {
    mode: "inline" | "fullscreen" | "pip" | "modal";
    params?: Record<string, unknown>;
  };
};

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;
  };
};