widget-design

Widget Design Best Practices

Decision Framework

Platform Selection

Choose based on target client:

• GPT Apps: Target is ChatGPT. Requires _meta.openai with widgetAccessible: true.
• MCP Apps: Target is any ext-apps client. Minimal config, works automatically.

Handler Type Selection

Scenario	Handler	Reason
User interaction needed (buttons, inputs)	React (.tsx)	State management with hooks
Display external widget library	Template literal	Just load scripts/styles
Dynamic content from tool params	React	Props flow naturally
Static HTML with no state	Template literal	Simpler, less overhead

Rule of thumb: If unsure, start with React. Converting later is harder than starting simple.

Widget Design Principles

1. Widgets Are Not Web Apps

Widgets render inline in conversations. Design constraints:

• No navigation: Single-screen experience only
• Limited width: ~600-700px max in most clients
• Sandboxed: External resources need CSP declarations
• Ephemeral: May be re-rendered, don't rely on persistence

2. Immediate Value

Show useful content without requiring user action:

// Bad: Requires click to see anything
export default function Widget() {
  const [data, setData] = useState(null);
  return <button onClick={fetchData}>Load Data</button>;
}

// Good: Shows data immediately
export default function Widget({ query }) {
  const [data, setData] = useState(null);
  useEffect(() => { fetchData(query).then(setData); }, [query]);
  return data ? <Results data={data} /> : <Loading />;
}

3. Visual Hierarchy in Limited Space

With limited width, hierarchy matters more:

<div className="space-y-4">
  {/* Label: small, muted, uppercase */}
  <div className="text-sm text-zinc-500 uppercase tracking-wider">Temperature</div>
  
  {/* Value: large, prominent */}
  <div className="text-5xl font-light">72°F</div>
  
  {/* Supporting: medium, secondary */}
  <div className="text-zinc-400">Feels like 68°F</div>
</div>