When a ChatGPT app needs UI instead of text
ChatGPT app UI vs text: choose tool output, inline cards, fullscreen or PiP using OpenAI’s Apps SDK guidance. If you are building a ChatGPT app, the hard UI decision is not…
Faisal Karkoh · 19 Oct 2026 · 11 min read
If you are building a ChatGPT app, the hard UI decision is not whether a richer interface is possible. It is whether that interface helps the user and the model complete the job better than clear text and structured tool results.
Use the smallest surface that completes the task: start with text and structured output, add an inline card or carousel only when it improves the immediate decision, move to fullscreen when the task needs space or editing, and reserve PiP for ongoing sessions that must remain visible while the conversation continues.
Evidence note: This article is based only on the supplied OpenAI Help Center, OpenAI developer documentation and OpenAI developer blog sources accessed on 2026-10-19. No live ChatGPT app was built, submitted, priced or tested for this brief. Example workloads are illustrative, not observed results.
The decision rule
OpenAI frames app value around Know, Do and Show. The Show test asks whether the app presents information in a clearer, more actionable UI than plain text, according to OpenAI’s developer blog on what makes a great ChatGPT app. That is the useful filter for ChatGPT app UI vs text: if the UI does not improve the user’s decision or action, it is probably extra surface area.
This choice is mainly for product managers, designers and engineers deciding how much Apps SDK interface to expose for a specific workflow. It is not a general rule that every ChatGPT app needs an embedded interface. A support lookup, data transformation, status check or single approval can often be better as model-visible text plus structured output, because the conversation itself is the product surface.
OpenAI also says ChatGPT apps are designed for two audiences: the human in the chat and the model runtime that decides when and how to call the app. A widget can look useful while still being a poor app surface if it hides context from the transcript, creates state the model cannot reason over, or makes confirmation less explicit. If the work is still at the product-definition stage, the same boundary-setting logic applies before implementation; see the companion workflow for turning feature ideas into scoped specs in ChatGPT prompts for planning a software feature.
For a concrete comparison, use an illustrative shortlist app. The app helps a user choose one item from 3–8 candidates, inspect details, then approve one write action such as saving the selected item or creating a record. Assume the candidates have an ID, name, short description, ranking reason and any required write-action fields. The same workload can fit different surfaces depending on how much comparison, editing and persistence the user really needs.
| Surface | Use when | Expected output | Main risk |
|---|
| Tool-only text and structured output | The shortlist is short, the ranking is obvious and confirmation fits in one sentence. | A concise answer plus structuredContent containing the candidates and selected recommendation. | Dense comparisons can become hard to scan. |
| Inline card | The app needs one compact confirmation, visual status or up to two primary actions. | A single card with the chosen item, the reason it was selected and one confirm action. | The card becomes crowded if it needs multiple views, forms or navigation. |
| Inline carousel | The user must compare 3–8 similar items before choosing one. | A carousel with concise metadata and at most one optional CTA per card. | Too many items or too much metadata can hide the best answer. |
| Fullscreen embedded UI | The user needs filtering, editing, detailed inspection, a long form, a diagram or a multi-step workspace. | A fullscreen component where the user can browse or edit while continuing to prompt through the ChatGPT composer. | Iframe, CSP, state and review complexity increase. |
| PiP | The activity is ongoing and should persist while the conversation continues. | A small persistent session view. | It is a poor fit for static dashboards or crowded controls. |
The stop condition is strict: do not escalate the surface if the same decision can be completed with clear text, concise structured data and a single explicit confirmation. The practical test is whether the user can confidently answer, “what am I approving, why, and what happens next?” without opening a separate view.
What ChatGPT can render
The Apps SDK is described by OpenAI as a preview developer toolkit for designing both the logic and interface of an app that runs inside ChatGPT. The OpenAI Help Center Apps SDK page says it is built on MCP and is open source. The same Help Center page says developers need permission to create custom apps in order to build and test with the Apps SDK preview. It also states that Business, Enterprise and Edu workspaces are supported for creating and testing custom apps, with workspace admin or owner controls; Enterprise and Edu admins can grant selected members permission. That is a preview-access constraint, not a UI design preference.
OpenAI’s reference lists the supported display modes, which matters because the article distinguishes documented modes from product-design shorthand like “side panel.”For rendering, keep the official modes precise. The OpenAI plugin and UI reference exposes inline, fullscreen and pip through resource metadata. It does not list a separate side panel display mode. If a product team asks for a side panel, do not automatically translate it to inline or fullscreen; first distinguish display modes from extension surfaces, because OpenAI’s Extensions docs separately describe conversation panels that open an app beside a conversation and thread side-panel entrypoints.
Tool results have three important data paths. The same reference explains that content exposes model-visible text, structuredContent exposes model-visible structured data, and _meta is delivered only to the component and hidden from the model. Only content and structuredContent appear in the conversation transcript; _meta can hydrate UI without exposing that data to the model.
That split is a real product limit, not just an implementation detail. If the selected item, write action or confirmation reason lives only in component-only state, the model cannot reliably refer to it later in the conversation. Put the decision record the model needs into structuredContent; keep UI-only hydration, display preferences or sensitive component data in _meta where appropriate.
A UI component is linked through _meta.ui.resourceUri. OpenAI’s UI build guide also says ChatGPT honours _meta["openai/outputTemplate"] as a compatibility alias. That linking mechanism is one reason to avoid adding UI unless the surface is doing real work. If the app also handles files, uploads or retrieval flows, separate those concerns from the display-mode decision; the file-routing side is covered in ChatGPT plugin file handlers.
When text and structured output are enough
Text-first output is enough when the task is simple, auditable and naturally conversational. That includes retrieval, transformation, explanation, status checks, IDs, short summaries and clear confirmations.
In the illustrative shortlist app, tool-only output is the right choice if three candidates are returned, one candidate clearly wins and the next step is to confirm saving it. The answer can state the recommendation, give the reason and ask for confirmation. The candidate list can go into structuredContent so the model can reason over it later in the conversation.
A useful text-first response for that workload might include the selected candidate ID, the top reason, the rejected alternatives in one line each and a direct confirmation question. The UI value is low if the user only needs to say “yes, save that one” or “show the second option instead”. Adding a component at that point can make the app feel heavier without improving the decision.
This is not a lesser app. A tool-only workflow is complete when the action and confirmation are unambiguous. It keeps the transcript clear, avoids iframe lifecycle issues and reduces the chance that the user acts on UI state the model cannot see. If a component is used later, keep sensitive or UI-only hydration data out of model-visible fields and place it in _meta, because OpenAI’s reference says _meta is forwarded to the component but hidden from the model.
When inline cards and carousels help
Inline is the default starting surface. OpenAI’s UI guidelines say the inline display mode appears directly in the flow of the conversation and that every app initially appears inline.
The inline guidance shows the compact surface the article recommends for lightweight decisions, confirmations, and short comparable lists.An inline card earns its keep when it supports a lightweight, single-purpose widget: a quick confirmation, a basic action, a visual aid or a small amount of structured data. In the shortlist example, a card makes sense if the selected item needs a visual status, one confirm action and perhaps one secondary action such as viewing details.
The limits are important. OpenAI says inline cards should support up to two primary actions, avoid deep navigation or multiple views, avoid nested scrolling and avoid duplicating ChatGPT inputs. If the card needs tabs, filters, long forms, multiple decisions or a mini admin panel, it is no longer a small card problem.
An inline carousel fits the same workload only when the user genuinely needs to compare several similar options before choosing. OpenAI recommends 3–8 items for inline carousels, with concise metadata and usually one optional CTA per card. With two items, text or a card will usually be clearer. With many more than eight, the better answer is often summarisation, filtering or a fullscreen surface where the user can inspect the set properly.
The comparison should stay narrow. A carousel is useful for choosing among similar candidates, not for burying a ranking that the model could have summarised. Each card should make one decision easier: recognise the candidate, understand the key difference and choose or inspect it. If each card needs paragraphs of explanation, the workflow probably needs a summary first or a larger workspace.
When fullscreen or PiP is justified
Fullscreen is the right escalation when the task needs space. OpenAI’s UI guidelines describe fullscreen as suitable for rich tasks that cannot be reduced to a single card, including interactive maps, rich editing canvases, interactive diagrams and browsing detailed content.
The fullscreen guidance shows why larger embedded UI is reserved for workflows that need space, inspection, editing, or multi-step interaction.In the shortlist example, move to fullscreen when the user needs filters, detailed inspection, a long approval form, editable fields, a diagram or a multi-step workspace. At that point, forcing the job into an inline card would either hide important information or create a cramped interaction.
Fullscreen does not mean leaving the conversational model behind. OpenAI says the ChatGPT composer remains present in fullscreen, allowing users to keep prompting in the context of the fullscreen view. Existing editors and admin interfaces may be embedded in fullscreen when they meet the iframe policy, according to the same OpenAI guidelines. A conventional web admin screen is not automatically a good ChatGPT app surface; it must still work inside the iframe, CSP and display-mode constraints.
The product question for fullscreen is whether the user is doing workspace work, not just viewing more content. Filtering a list, editing fields, reviewing a diagram and completing a multi-step approval can justify the larger surface. A static report, simple dashboard or one-off confirmation usually cannot.
PiP is for persistence, not decoration. OpenAI’s UI guidelines describe picture-in-picture as a persistent floating window inside ChatGPT for ongoing or live sessions such as games, live collaboration, quizzes or learning sessions.
The PiP guidance supports the article’s distinction between persistent live sessions and static content better handled inline or fullscreen.For the shortlist workload, PiP is rarely justified because choosing an item and approving a write action is a bounded decision. It becomes a PiP candidate only if the selection process is part of an ongoing session that must remain visible while the user continues chatting. Do not use PiP for static content that could be shown inline or for dense controls that need fullscreen space; OpenAI specifically warns not to overload PiP with controls or static content better suited to inline or fullscreen.
Implementation guardrails
The surface choice should shape the implementation. For many UI integrations, OpenAI recommends separating data tools from render tools: data tools fetch, compute or mutate and return tool results, while separate render tools return the widget template. The OpenAI UI build guide warns that attaching a widget template to every tool call can cause ChatGPT to re-render the iframe too often.
In that decoupled pattern, only the render tool should include _meta.ui.resourceUri. Data tools should return the text and structured data needed for reasoning and confirmation. The render tool should be used when a component is actually needed.
For the shortlist app, that means the search or ranking tool can return candidate IDs, labels, ranking reasons and the recommended action in structuredContent. A separate render tool can present those candidates as a card, carousel or fullscreen view only after the model has enough context to decide that a component will help. The write tool should still validate the selected candidate and user consent on the server side before creating or updating a record.
State ownership also matters. OpenAI distinguishes authoritative business data, ephemeral UI state and durable cross-session state. The UI should render authoritative business data from tool results and layer temporary presentation state on top. For the shortlist app, the selected candidate and write confirmation should come from the authoritative tool result, not from an unvalidated client-side assumption.
A practical failure case is a component that lets the user select item B while the model-visible transcript still refers to item A. Avoid that mismatch by keeping the decision-critical fields model-visible, asking for explicit confirmation before writes, and treating component state as presentation until a server-validated tool call records the action.
The security burden rises as soon as a widget is involved. OpenAI’s security and privacy guidance says widgets run in isolated iframes with a strict CSP, cannot access some privileged browser APIs, and do not get nested frames by default. Specific origins must be enabled through resource CSP metadata where needed. For a fuller architecture view of authentication, data access and deployment boundaries around MCP-style apps, see secure MCP apps on Vercel with Supabase.
Apply the same safety rule regardless of surface: least privilege, explicit user consent, server-side validation, minimal structured content for the current prompt, and no secrets or tokens in component props. If the app is part of an existing SaaS product rather than a standalone demo, the same constraint-first approach matters before you add any AI surface; adding AI to your SaaS without blowing it up covers that broader product integration decision.
The next action is to write the app’s main user decision in one sentence, list the minimum data the model needs to complete it, then choose the smallest documented display mode that makes that decision clearer.