Inline UI & Widgets in ChatGPT Apps
One-liner: Great ChatGPT Apps win on UI that finishes the job. With MCP, you render inline widgets—forms, tables, cards, media, and confirmations—directly inside the conversation so users can input, review, and confirm without leaving chat.
If you’re just getting started, read What Are ChatGPT Apps?, How ChatGPT Apps Work, and the protocol overview MCP (Model Context Protocol). To wire a server, see MCP Server Tutorial. For a full build, follow Apps SDK Tutorial.
Why inline UI matters
- Speed to value: single-screen interactions (≤60s to first success).
- Lower cognitive load: structured inputs beat long prompts.
- Trust & safety: explicit confirmations around write actions and payments.
- Measurable funnels: you can instrument view → submit → success. See App Analytics.
Core widget types (mental model)
Below are descriptor examples to illustrate common patterns. Exact shapes may vary by SDK, but the concepts hold.
1) Form (collect inputs)
{
"type": "form",
"title": "Trip Planner",
"fields": [
{ "id": "city", "type": "text", "label": "Destination", "required": true },
{ "id": "dates", "type": "daterange", "label": "Dates", "required": true },
{ "id": "budget", "type": "number", "label": "Budget (USD)", "min": 100 }
],
"submitLabel": "Search"
}
Tips
- Prefer selects/sliders over free text where possible.
- Use constraints (min/max, regex) to cut validation loops.
2) Table (compare options)
{
"type": "table",
"title": "Flight Options",
"columns": [
{"key":"carrier","label":"Airline"},
{"key":"depart","label":"Depart"},
{"key":"arrive","label":"Arrive"},
{"key":"price","label":"Price"}
],
"dataBinding": "output.flights",
"rowActions": [
{"id":"select","label":"Select"}
],
"pagination": {"pageSize": 10}
}
Tips
- Keep 4–6 columns max.
- Add rowActions for one-click selects.
3) Card (summaries & media)
{
"type": "card",
"title": "Hotel Pick",
"subtitle": "Shinjuku • 4.5★",
"media": {"type":"image","src":"https://.../photo.jpg"},
"items": [
"Near JR station",
"Free breakfast",
"24h desk"
],
"actions": [
{"id":"book","label":"Book"},
{"id":"save","label":"Save"}
]
}
Use for quick previews, recommendations, receipts, and confirmations.
4) Steps/Progress (long jobs)
{
"type":"progress",
"title":"Building itinerary…",
"status":"loading",
"details":[
{"label":"Flights","state":"done"},
{"label":"Hotels","state":"loading"},
{"label":"Activities","state":"queued"}
]
}
Stream updates as tasks complete; avoid blank screens.
5) Confirmation (destructive/write actions)
{
"type":"confirm",
"title":"Create calendar event?",
"body":"Add 'Team Review' on Tue 2pm, 30 min, with 5 attendees.",
"confirmLabel":"Create Event",
"cancelLabel":"Cancel"
}
Pair confirmations with least-privilege scopes. See Security for ChatGPT Apps.
6) Payment (ACP handoff)
{
"type":"checkout",
"title":"Itinerary Pro",
"lineItems":[{"name":"Trip plan","amount":12000,"currency":"USD"}],
"afterSuccess":{"type":"message","text":"Receipt sent to your email."}
}
Implements Agentic Commerce Protocol. Learn more in Agentic Commerce Protocol and How In-Chat Checkout Works.
High-converting page flows (copy these)
- Form → Table → Confirm
- For searches and comparisons (flights, listings, products).
- Add rowActions (“Select”, “Shortlist”) then a confirm widget.
- Form → Card Preview → Export/Save
- For generation/editing (design, summaries, docs).
- Offer Export and Save actions as primary buttons.
- Form → Progress → Card(s) → Checkout
- For multi-API workflows (travel bundles, orders).
- Use progress, then show 2–3 curated options with checkout.
UI validation & error patterns
- Inline field errors (per-field messages, not generic alerts).
- Top-level alert for tool failures with “Try again” action.
- Time-boxed retries for flaky APIs (exponential backoff).
- Empty states (e.g., “No matches—try a wider date range.”)
Resilience: MCP Server Tutorial • Apps SDK Tutorial
Accessibility & copywriting tips
- Labels > placeholders; never rely solely on placeholder text.
- Use sentence case, concrete verbs (“Create playlist”, “Save itinerary”).
- Maintain keyboard operability for all actions.
- Keep reading level around Grade 7–9 for mass-market apps.
Performance guidelines
- Aim for ≤300ms UI render + visible loading state within 500ms.
- Stream partial results where possible.
- Paginate and lazy-load media.
- Pre-validate input client-side to prevent tool round-trips.
Security & privacy in UI
- Progressive consent: request scopes only when needed; explain why.
- Sensitive actions (writes, payments) must use confirm widgets.
- Avoid echoing secrets or PII in UI; mask in logs.
- Provide undo or “view changes” where possible.
Playbooks: Security • Data Privacy • Secrets Handling • Compliance & PII
Template: “Hero flow” UI bundle
{
"form": {
"type":"form",
"title":"Plan a 3-day Tokyo trip",
"fields":[
{"id":"dates","type":"daterange","label":"Dates","required":true},
{"id":"budget","type":"number","label":"Budget (USD)","min":300},
{"id":"focus","type":"select","label":"Focus","options":["Food","Culture","Nightlife"],"required":true}
],
"submitLabel":"Find options"
},
"progress":{"type":"progress","title":"Working…"},
"results":{
"type":"table",
"title":"Top Picks",
"columns":[
{"key":"name","label":"Name"},
{"key":"neighborhood","label":"Area"},
{"key":"price","label":"Price"}
],
"rowActions":[{"id":"details","label":"View"}],
"dataBinding":"output.options"
},
"confirm":{"type":"confirm","title":"Book this option?"}
}
Review checklist (UI)
- ✅ One hero flow that ends in a clear confirmation/export/checkout
- ✅ Forms use selects/sliders where possible; strict validation rules
- ✅ Tables/cards limited to what users need to decide
- ✅ Progress/empty states; no dead-ends
- ✅ Friendly, plain-language error messages
- ✅ Screenshots in your listing match actual UI
For submission, see App Submission and App Verification & Review.