Building Widgets

Quick Start

The fastest way to create a widget:

fastapps create mywidget

This creates:

server/tools/mywidget_tool.py - Python backend logic
widgets/mywidget/index.jsx - React frontend component

Core Concepts

1. Data Flow

MCP Tool → window.openai	The MCP tool returns toolOutput and metadata, which are stored inside window.openai.
window.openai → React Component	The component reads data (like tool input/output, theme, layout) from window.openai using hooks such as useWidgetProps or useOpenAiGlobal.
React Component → useWidgetState	User interactions (clicks, filters, toggles) are handled in React and synchronized with the host through useWidgetState.
useWidgetState → window.openai.setWidgetState	When state changes, it’s sent to the host via window.openai.setWidgetState() for persistence.
window.openai → ChatGPT Host Context	ChatGPT stores the widget state persistently, so it’s available across sessions and visible to the model for reasoning.

2. File Structure

widgets/
  mywidget/
    index.jsx          # React component
server/tools/
  mywidget_tool.py     # Python backend

3. React Hooks

useWidgetProps() - Access tool output data
useWidgetState() - Manage persistent state
useOpenAiGlobal() - Access ChatGPT environment
useDisplayMode() / useMaxHeight() - Layout convenience hooks

Next Steps

Ready to start building?

Widget Basics

Learn the fundamentals

React Hooks

Master the hook system

Advanced Patterns

Complex interactions

Introduction

Getting Started

Widgets

Server

Authentication

Quick Start

Widget Architecture

Core Concepts

1. Data Flow

2. File Structure

3. React Hooks

Next Steps

Widget Basics

React Hooks

Advanced Patterns

​Quick Start

​Widget Architecture

​Core Concepts

​1. Data Flow

​2. File Structure

​3. React Hooks

​Next Steps

Widget Basics

React Hooks

Advanced Patterns

Quick Start

Widget Architecture

Core Concepts

1. Data Flow

2. File Structure

3. React Hooks

Next Steps