Use skybridge/web

Add React hooks and utilities to your App widgets with skybridge/web standalone package.

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 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 Apps:

State Management

• useToolInfo: Get initial tool input, output and metadata
• useWidgetState: Persist state across widget renders

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

• 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

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 an App, please read the Core Concepts and Interaction Model sections below.

MCP Fundamentals

Learn the fundamentals of MCP servers and Apps

Data Flow

Understand how tools, widgets, and the model communicate

Type Safety

End-to-end type inference from server to widget