TypeScriptUI WidgetsWidget SDK
Hooks
useWidgetSDK, useTheme, useDisplayMode, useWidgetState, and more
Hooks are the usual way to use the SDK from a React component. Each one re-renders your component when the value it returns changes.
useWidgetSDK()
Primary hook for accessing all Widget SDK functionality.
Returns:
{
sdk: WidgetSDK;
isReady: boolean;
// State Management
setState: (state: any) => Promise<void>;
getState: () => any;
// Tool Calling
callTool: (name: string, args?: Record<string, unknown>) => Promise<CallToolResponse>;
// Display Controls
requestFullscreen: () => Promise<void>;
requestInline: () => Promise<void>;
requestPip: () => Promise<void>;
requestDisplayMode: (mode: DisplayMode) => Promise<{ mode: DisplayMode }>;
requestClose: () => void;
// Navigation
openExternal: (url: string) => void;
sendFollowUpMessage: (prompt: string) => Promise<void>;
// Data Access
getToolInput: <T>() => T | null;
getToolOutput: <T>() => T | null;
getToolResponseMetadata: <T>() => T | null;
getTheme: () => 'light' | 'dark';
getMaxHeight: () => number;
getDisplayMode: () => DisplayMode;
getUserAgent: () => UserAgent | null;
getLocale: () => string;
getSafeArea: () => SafeArea | null;
}Example:
function InteractiveWidget() {
const { isReady, callTool, getToolOutput, requestFullscreen } = useWidgetSDK();
const handleAction = async () => {
const result = await callTool('process_data', { id: '123' });
console.log('Tool result:', result);
};
return (
<div>
<button onClick={handleAction}>Process</button>
<button onClick={requestFullscreen}>Fullscreen</button>
</div>
);
}useTheme()
Get the current theme (light or dark mode).
Returns: 'light' | 'dark' | null
Example:
function ThemedWidget() {
const theme = useTheme();
const styles = {
background: theme === 'dark' ? '#1a1a1a' : '#ffffff',
color: theme === 'dark' ? '#ffffff' : '#000000',
border: `1px solid ${theme === 'dark' ? '#333' : '#ddd'}`
};
return <div style={styles}>Theme-aware content</div>;
}useDisplayMode()
Get the current display mode.
Returns: 'inline' | 'fullscreen' | 'pip' | null
Example:
function ResponsiveWidget() {
const displayMode = useDisplayMode();
const padding = displayMode === 'fullscreen' ? '48px' : '16px';
const fontSize = displayMode === 'fullscreen' ? '24px' : '16px';
return (
<div style={{ padding, fontSize }}>
{displayMode === 'fullscreen' ? 'Fullscreen View' : 'Compact View'}
</div>
);
}useMaxHeight()
Get the maximum height constraint for the widget.
Returns: number | null
Example:
function ScrollableWidget() {
const maxHeight = useMaxHeight();
return (
<div style={{
maxHeight: maxHeight ? `${maxHeight}px` : 'none',
overflow: 'auto'
}}>
<LongContent />
</div>
);
}useWidgetState()
Manage persistent widget state with automatic synchronization.
Returns:
{
state: T | null;
setState: (value: T | ((prev: T) => T)) => Promise<void>;
isLoading: boolean;
}Example:
interface FormState {
name: string;
email: string;
}
function StatefulWidget() {
const { state, setState, isLoading } = useWidgetState<FormState>();
const updateName = (name: string) => {
setState(prev => ({ ...prev, name }));
};
return (
<div>
<input
value={state?.name || ''}
onChange={(e) => updateName(e.target.value)}
/>
</div>
);
}useOpenAiGlobal()
Subscribe to specific window.openai properties with automatic re-rendering on changes.
Parameters:
key: keyof OpenAiGlobals- Property to subscribe to
Returns: Property value or null
Example:
function LocaleWidget() {
const locale = useOpenAiGlobal('locale');
const userAgent = useOpenAiGlobal('userAgent');
return (
<div>
<p>Locale: {locale}</p>
<p>Device: {userAgent?.deviceType}</p>
</div>
);
}