@devries-cameron20 / composio-1 / commits / 09a36cc63
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: show connection links as cards (DEVREL-201) (#5375)

## Summary Developers building chat interfaces could find instructions for forwarding Composio authentication links, but no example of displaying those links as connection cards. This adds a React example for `COMPOSIO_MANAGE_CONNECTIONS` results to the authentication guide. Addresses [DEVREL-201: Provide an example of custom connector link UI](https://linear.app/composio/issue/DEVREL-201/provide-an-example-of-custom-connector-link-ui). Designated PR reviewer: @jkomyno. ## Changes - Add `ConnectionCards`, a React component that validates decoded tool results with Zod and renders a card for each toolkit's `initiated`, `active`, or `failed` connection state. - Include a sample result, explain how to route tool output to the component, and require a fresh connection-status check before resuming app tools. - Link to callback configuration and white-label authentication for other connection flows. The card opens the existing hosted authentication URL. ## Type of change - [ ] Bug fix - [ ] New feature - [ ] Refactor/Chore - [x] Documentation - [ ] Breaking change ## How Has This Been Tested? At head `48c3d7288f69d2a3b50e99effe6c8355e9544f2d`: - Re-ran `cd docs && bun run check:code-examples` before opening this PR, using existing shared dependencies without installing packages. Exit 0: ```text No code example violations in 449 file(s). ``` - `git diff --check origin/next...HEAD` passed. `git merge-tree --write-tree origin/next HEAD` completed without conflicts. - During implementation at this same head, extracted the documented TSX component and type-checked it with strict TypeScript settings. Rendered it with React's `renderToStaticMarkup` to check pending, connected, failed, missing-link, unsuccessful, malformed, multiple-toolkit, unsafe-URL, and escaped-error cases. The sample JSON also passed validation against the committed meta-tool response schema, and the MDX compiled. These were temporary checks, not committed test files. - Full link checking was attempted during implementation but could not run because the worktree lacked the generated `fumadocs-mdx:collections/server` module. Added link targets were checked directly against their source pages. - No dependency installation or `next build` was run. No live authentication flow was tested. ## Screenshots (if applicable) No browser screenshots were captured. This adds a documented component rather than changing the docs site's UI. The example accepts the decoded tool result in an existing React chat renderer: ```tsx <ConnectionCards result={toolResult} /> ``` | Input state | Rendered output | | --- | --- | | `initiated` with an HTTPS `redirect_url` | Connect button opening the returned URL in a new tab | | `active` | Connected status | | `failed` | Error message | | Malformed or unsuccessful result | Validation error message | ## Checklist - [ ] I have read the Code of Conduct and this PR adheres to it - [ ] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the third-party links policy; this change adds internal docs links only - [ ] I ran linters/tests locally and they passed; the passing checks and link-check limitation are listed above - [x] I updated documentation as needed - [x] I added tests or explain why not applicable; this is a docs-only example, checked with the temporary rendering and schema checks above - [ ] I added a changeset if this change affects published packages; not applicable to this docs-only change ## Additional context The agent wrote and checked the example. Brendan requested the work and authorized opening this PR; human review of the full diff remains outstanding. In plain words: the example turns an account connection link into a card in your chat. Opening the link starts authentication, and the card shows success only after Composio confirms the connection.

Brendan O'Leary committed Nov 13, 2026 at 11:16 UTC 09a36cc63a823a7275d00e0027792c3cb4634699
1 file changed +77
docs/content/docs/authentication/index.mdx
+77
@@ -67,6 +67,83 @@ The agent posts the Connect Link straight into the conversation. The user clicks
67
68 You can also call `COMPOSIO_MANAGE_CONNECTIONS` yourself, intercept the Connect Link, and surface it wherever you need: DM it to the user, render it in your own UI, or email it. See [redirect auth links](/examples/general-agent-with-pi#redirect-auth-links) for a worked example.
69
70 +### Render connection links as cards
71 +
72 +Your chat UI can render the result of `COMPOSIO_MANAGE_CONNECTIONS` as a card with a connect button. Keep the returned URL unchanged. The button opens the hosted authentication flow; you control the card's layout and copy.
73 +
74 +In your chat's tool-result renderer, pass the decoded JSON result for `COMPOSIO_MANAGE_CONNECTIONS` to this React component. It reads `data.results`, a map of toolkit connection results, and handles `initiated`, `active`, and `failed` states. Install `zod` alongside React to validate the tool result at the UI boundary.
75 +
76 +{/* code-example: single-language reason="React TSX component renders an existing tool result locally; it makes no SDK or API calls" */}
77 +```tsx title="ConnectionCards.tsx"
78 +import { z } from 'zod';
79 +
80 +const connectionResultSchema = z.object({
81 + successful: z.literal(true),
82 + data: z.object({
83 + results: z.record(z.string(), z.object({
84 + toolkit: z.string(),
85 + status: z.enum(['initiated', 'active', 'failed']),
86 + redirect_url: z.url({ protocol: /^https$/ }).nullish(),
87 + error_message: z.string().nullish(),
88 + })),
89 + }),
90 +});
91 +
92 +export function ConnectionCards({ result }: { result: unknown }) {
93 + const parsed = connectionResultSchema.safeParse(result);
94 + if (!parsed.success) {
95 + return <p role="alert">Could not load connections. Please try again.</p>;
96 + }
97 +
98 + return (
99 + <div>
100 + {Object.entries(parsed.data.data.results).map(([slug, connection]) => (
101 + <article key={slug} aria-label={`${connection.toolkit} connection`}
102 + style={{ border: '1px solid #888', borderRadius: 12, padding: 16, marginBottom: 12 }}>
103 + <h3>{connection.toolkit}</h3>
104 + {connection.status === 'active' ? (
105 + <p>Connected</p>
106 + ) : connection.status === 'initiated' && connection.redirect_url ? (
107 + <>
108 + <p>Connect your account to continue.</p>
109 + <a href={connection.redirect_url} target="_blank" rel="noopener noreferrer">
110 + Connect {connection.toolkit} (opens in a new tab)
111 + </a>
112 + </>
113 + ) : (
114 + <p role="alert">{connection.error_message ?? 'Could not start the connection. Please try again.'}</p>
115 + )}
116 + </article>
117 + ))}
118 + </div>
119 + );
120 +}
121 +```
122 +
123 +For example, this tool result produces a GitHub card with a connect button. The URL is a placeholder; use the URL from the actual tool result.
124 +
125 +```json
126 +{
127 + "successful": true,
128 + "data": {
129 + "message": "Complete authentication to continue.",
130 + "results": {
131 + "github": {
132 + "toolkit": "github",
133 + "status": "initiated",
134 + "redirect_url": "https://connect.composio.dev/link/ln_example"
135 + }
136 + }
137 + }
138 +}
139 +```
140 +
141 +Route the structured tool result to the card before converting tool output to chat text. With SDK-executed session tools, `session.tools({ afterExecute })` lets your server inspect the result before the model sees it. Send it only to the authenticated user's chat through your app's existing transport. MCP clients need to handle rendering in the client because SDK modifiers don't run [over MCP](/docs/sessions-via-mcp#trade-offs).
142 +
143 +Opening the link does not mean the account is connected. After the user finishes authentication, call `COMPOSIO_MANAGE_CONNECTIONS` again for the same toolkit and session. Update the card from the new result and resume app tool calls only when the toolkit's status is `active`. You can use the [callback URL](#custom-callback-url) below to return the user to your app.
144 +
145 +For your own credential forms or OAuth flow, see [White-labeling authentication](/docs/authentication/white-labeling-authentication).
146 +
147 ### Custom callback URL
148
149 To send users back to your app after they connect, pass a `callback_url`: