--- name: visualize description: Render rich interactive visuals — SVG diagrams, HTML widgets, Chart.js charts, interactive explainers — directly inline in chat using the render_visualization tool. Use whenever the user asks to visualize, diagram, chart, draw, map out, or illustrate something, or when a topic has spatial, sequential, or systemic relationships a diagram would clarify better than prose. Also use proactively for data comparisons, metrics, architecture, processes, or mechanisms that benefit from a visual. --- # Inline Visualizer Render rich interactive visuals directly inline in chat using `render_visualization`. Supports **live streaming** — the iframe fills in token-by-token as you generate the HTML/SVG. ## How to use You call the tool with **only a title**, and then emit the HTML/SVG content wrapped in the **plain-text delimiters** `@@@VIZ-START` and `@@@VIZ-END`. The wrapper tails your stream and paints the iframe live. 1. Call `render_visualization(title="…")` 2. In your text response, write explanatory prose 3. Open with `@@@VIZ-START` on its own line 4. Emit the HTML/SVG **content fragment only** — **NEVER** wrap in ``, ``, ``, or `` tags (the iframe already has these; duplicating them corrupts the DOM) 5. Close with `@@@VIZ-END` on its own line 6. Continue with any follow-up prose The raw markers + SVG source are auto-hidden from the chat — users see only the rendered iframe filling in live. **Example response structure:** ``` I'll visualize the attention mechanism for you. @@@VIZ-START @@@VIZ-END As you can see, each query token attends to all key tokens simultaneously. ``` **Why plain-text delimiters, not a code fence?** The previous `` ```visualization `` protocol went through Open WebUI's CodeBlock / CodeMirror editor, which virtualizes content and drops scrolled-off lines from the DOM. The `@@@VIZ-START` / `@@@VIZ-END` markers are ordinary paragraph text — no editor, no virtualization, no edge cases. **Streaming rules:** - Use the delimiters EXACTLY `@@@VIZ-START` and `@@@VIZ-END` — case-sensitive, on their own lines. Do NOT put the content inside `` ``` ``, `~~~`, or `:::` fences. - Do NOT wrap in HTML tags like `` or `

``` **Chart rules:** - Wrap canvas in container with `position: relative` and explicit height - Always `responsive: true`, `maintainAspectRatio: false` - Read CSS variables for text/border colors — never hardcode - `borderRadius: 4` on bars - Line charts: `tension: 0.3` for smooth curves - Doughnut: `cutout: '60%'` — never use pie **Chart type selection:** | Data shape | Type | Notes | |-----------|------|-------| | Categories + values | Bar | Horizontal if labels are long | | Time series | Line | tension: 0.3 | | Parts of whole | Doughnut | cutout: '60%' | | Two variables | Scatter | Add trend line if relevant | ### Inline SVG charts (no library) Horizontal bar: ```svg ``` --- ## Component patterns ### Metric cards ```html

Label

$3,870

``` ### Comparison layout Side-by-side cards with a shared header row, metrics in each column. ### Interactive explainer Sliders or buttons that update visible state via JavaScript. Example: a slider controlling a variable with a live-updating SVG or value display. --- ## sendPrompt bridge — conversational diagrams `sendPrompt(text)` is the function that makes visualizations conversational. When called, it injects the given text into the chat input field and submits it — exactly as if the user had typed and sent it themselves. The model then receives that message and responds normally, creating a feedback loop between the visual and the conversation. This is what separates a static diagram from an **exploration interface**. A user sees a system architecture diagram, clicks on the "Load Balancer" node, and the model receives "Tell me more about the load balancer — how does it distribute traffic across the backend services?" as a user message. The model then responds with details, and could even generate a *new* sub-diagram showing the load balancer internals. The user never had to type anything — they just clicked. ### Why this matters Without sendPrompt, interactive elements inside the iframe are isolated — they can toggle visibility, animate, or filter data, but they can never talk back to the model. The user sees a cool diagram but has to manually type follow-up questions. With sendPrompt, every clickable element becomes a conversation starter. The diagram itself becomes a navigation interface for the topic. ### How it works technically The function is auto-injected by the tool. It uses Open WebUI's native `postMessage` protocol to submit the text as a user message. If the AI is still generating a response, the message is automatically queued and sent once generation completes. This requires **iframe Sandbox Allow Same Origin** to be enabled in Open WebUI settings — without it, the function silently fails (the visualization still works, but clicks do nothing). ### Writing good sendPrompt text The text you pass to sendPrompt becomes the user's message to the model. Write it as a natural follow-up question — conversational, specific, and referencing the context of the diagram: **Good prompt text** (specific, contextual, references the diagram): - `"Explain the attention mechanism — how does it decide which tokens to focus on?"` - `"Break down the CI/CD pipeline stage. What tools are typically used here?"` - `"Show me a more detailed diagram of the data processing layer"` - `"What happens when the load balancer detects a failed backend node?"` - `"Compare the pros and cons of the monolith vs microservices approach shown here"` **Bad prompt text** (vague, generic, loses context): - `"Tell me more"` — more about what? - `"Explain"` — explain what? - `"Details"` — not a sentence, model won't know what to do ### Usage patterns Simple patterns — single-click sendPrompt on a node or button: - **Drill-down**: `onclick="sendPrompt('Explain the API gateway — what does it handle?')"` on a diagram node - **Quiz answer**: `onclick="sendPrompt('I chose B: O(n log n). Am I right? Explain why.')"` on answer buttons - **Guided exploration**: `onclick="sendPrompt('Show me a more advanced example with edge cases.')"` on a "Go deeper →" button - **Comparison**: `onclick="sendPrompt('Compare REST vs GraphQL — when should I use each?')"` on one of two nodes **Form / preference collector** — gather multiple user selections, then send them all at once. Use local JS to track choices (button highlights, state object) and a submit button that composes a sendPrompt from the collected answers: ```html

What's your style?

Pace

Focus

``` This pattern is powerful because the model receives a structured summary of all user preferences in one message. Use local JS for the selection UI (instant feedback), then sendPrompt only on final submit. ### When to use sendPrompt vs local JS: | User action | Use | Why | |------------|-----|-----| | Learn more about a component | `sendPrompt` | Model gives a contextual explanation | | Explore a stage / drill down | `sendPrompt` | Model can generate a sub-diagram | | Submit answers or preferences | `sendPrompt` | Model evaluates or personalizes | | Toggle views, adjust sliders | Local JS | Instant feedback, no reasoning needed | | Filter/sort data | Local JS | Instant response, no model needed | --- ## Interactivity by default Build dashboards, charts, graphs, interactive functions, animated sections, moving objects, explandable detail sections, cards, copyable text elements and more. If the topic allows and it makes sense for the topic, build complex and visually stunning elements. Visualizations should feel alive and polished — not static images dumped into chat. Build interfaces that invite interaction: - **Expandable sections** — use collapsible `

` elements or JS-toggled sections so users can explore at their own pace without overwhelming them upfront - **Hover effects** — nodes, buttons, and cards should respond to hover (the `.node` class adds this for SVG elements; for HTML, use `:hover` styles) - **Smooth transitions** — add `transition: all 0.2s ease` to interactive elements for a polished feel - **Active states** — when a user selects an option or clicks a tab, make the selection visually clear with the `.active` class or distinct styling - **Progressive disclosure** — show a clean overview first, let the user click to reveal detail (tabs, accordions, or sendPrompt for model-powered drill-down) **The goal is to build something that feels like a real app component embedded in chat with reactivity, sections and extra elements** — not a screenshot. If the visualization has multiple facets, give the user controls to explore them. If it has hierarchical information, let them expand and collapse. If it has data, let them sort or filter. --- ## openLink bridge — opening URLs from visualizations `openLink(url)` opens a URL in a new browser tab from within the visualization iframe. Normal `` links inside an iframe can behave unpredictably (opening inside the iframe, being blocked by sandbox restrictions, etc.). This function handles that by opening the link in the parent window instead. ```html ``` Or in SVG: ```svg View source ↗ ``` Use `openLink` for external references, documentation links, or source code links. Unlike `sendPrompt`, this navigates away from the chat — use it when the user needs to access an external resource, not when they need the model to explain something. --- ## copyText + toast bridges — feedback on user actions `copyText(text)` copies `text` to the system clipboard and automatically shows a localized "Copied" toast in the top-right corner of the iframe. Works from HTTPS and HTTP origins (falls back to `execCommand('copy')` if the async Clipboard API is blocked). Use this on "Copy" buttons inside interactive visualizations — data tables, code snippets, shareable values. ```html ``` `toast(message, kind)` shows a small auto-dismissing banner inside the iframe. `kind` is optional and controls the text color: `'success'` (green, default), `'info'` (blue), `'warn'` (amber), `'error'` (red). Use it for status notifications inside long-running interactive tools — "Calculation done", "Invalid input", etc. ```html ``` Toasts auto-dismiss after ~2.2 s and stack vertically if fired in quick succession. --- ## saveState + loadState bridges — persistent interactive state `saveState(key, value)` and `loadState(key, fallback)` proxy `parent.localStorage` with a key prefix scoped to **this assistant message**. State survives page reloads and tab switches, but two different chats (or different messages in the same chat) each get their own independent state — no cross-contamination. ```html ``` Use it for: selected tabs, picked chart range, hidden/shown layers, theme overrides, collapsed sections — anything the user would expect to be remembered when they re-open the chat. Values are JSON-serialized. If `localStorage` is blocked (private browsing, sandboxed), both functions silently no-op and `loadState` returns `fallback`. --- ## CDN libraries — batteries included The strict-mode CSP allowlists three major CDN hosts, so the model can load **any library** served from them without touching any plugin setting. Prefer these over self-hosted paths for reliability. Allowed hosts: - `cdnjs.cloudflare.com` — Cloudflare's CDN, widest coverage - `cdn.jsdelivr.net` — npm / GitHub-backed, good for minor-version pinning - `unpkg.com` — npm mirror, same as jsdelivr Recommended libraries for visualization work: | Library | Why reach for it | Example loader | |---------|------------------|----------------| | **Chart.js** | Bar / line / doughnut / scatter charts with animation out of the box | `` | | **D3.js** | Custom data-driven SVG (force graphs, arcs, maps, non-standard charts) | `` | | **Vega-Lite** | Declarative grammar of graphics — feed it a JSON spec, it draws the chart | `` | Any other library on those three CDNs also works — vis-network, d3-force, echarts, apexcharts, plotly, tone.js, wavesurfer, etc. The host auto-detects completion and executes your ` ``` ### 2 · Script order External ` ``` You do NOT need `DOMContentLoaded` or `window.onload` wrappers — by the time your script runs, the entire fragment (except any later-positioned siblings) is already in the DOM. --- ## Quick reference | Rule | Value | |------|-------| | SVG viewBox width | Always 680px | | Font sizes | 14px labels, 12px subtitles | | Stroke width | 0.5px for borders | | Max colors per diagram | 2–3 ramps | | Subtitle max length | 5 words | | Corner radius (SVG) | rx=4 default, rx=8 emphasis | | Corner radius (HTML) | var(--radius-md) or -lg | | Min font size | 11px | | Heading sizes | h1=22px, h2=18px, h3=16px | ## Common failures 1. **Arrow through a box** — trace coordinates against every box 2. **Text overflow** — check (text_width + 2×padding) fits the rect 3. **viewBox too small** — content clipped at bottom 4. **viewBox too large** — creates wasteful empty space below the diagram. Calculate actual content bottom + 40px 5. **Floating labels** — every text needs a box, legend, or leader line 6. **Connector without fill="none"** — renders as black shape 7. **Missing dominant-baseline="central"** — text sits 4px too high 8. **Missing arrow marker in defs** — always include it 9. **Hardcoded colors** — always use CSS variables or ramp classes 10. **Chart.js canvas collapsed to 0 height** — wrap every canvas in `

` and set `maintainAspectRatio: false` 11. **Document wrapper tags** — never emit ``, ``, ``, or ``. The iframe shell already provides these. Including them mangles the DOM and breaks script execution