Skip to main content

​
Use skybridge/web

This guide shows you how to use skybridge/web without skybridge/server to add React hooks and utilities to your widgets.

​
Prerequisites

You should already have:
  • A working ChatGPT app MCP server backend (in any technology)
  • Node.js 24+

​
Install

Add Skybridge to your project: 
pnpm add skybridge

​
Package overview

skybridge/web provides React hooks and utilities for building advanced ChatGPT Apps:

​
State Management

​
User Interface

  • useLayout: Get the current user layout and visual environment information
  • useDisplayMode: Get and request widget display mode changes
  • useRequestModal: Open a modal portaled outside of the widget iframe
  • useUser: Get the session-stable user information (locale and userAgent)

​
Actions

​
Others

  • useAppsSdkContext: Low-level hook to subscribe to window.openai state values
  • generateHelpers: Generate typed helpers for your widgets (requires skybridge/server)
Each hook is documented in the API Reference section in the sidebar.

​
Basic example

Here’s a simple widget using Skybridge hooks: 
import { mountWidget, useToolInfo } from "skybridge/web";

const MyWidget: React.FC = () => {
  const toolInfo = useToolInfo();

  if (toolInfo.isPending) {
    return <div>Loading...</div>;
  }

  if (toolInfo.isSuccess) {
    return (
      <div>
        <h2>Results</h2>
        <pre>{JSON.stringify(toolInfo.output.structuredContent, null, 2)}</pre>
      </div>
    );
  }

  return <div>No results</div>;
};

mountWidget(<MyWidget />);

​
Type safety without server

If you’re not using skybridge/server, you won’t get automatic type inference. You can still add types manually: 
import { useToolInfo } from "skybridge/web";

interface MyToolInput {
  query: string;
  limit?: number;
}

const MyWidget: React.FC = () => {
  const toolInfo = useToolInfo<MyToolInput>();

  // toolInfo.input is now typed as MyToolInput
  console.log(toolInfo.input.query);

  return <div>Widget content</div>;
};

​
Learn more

To learn more about how to build a ChatGPT App, please read the Core Concepts and Iteraction Model sections below.

MCP Fundamentals

Learn the fundamentals of MCP servers and ChatGPT Apps

Data Flow

Understand how tools, widgets, and the model communicate

Type Safety

End-to-end type inference from server to widget