Build and refine HTML report pages

HTML pages let you build a complete custom report experience with HTML, CSS, SVG, canvas, and browser JavaScript. The assistant can design an entire page, connect its components to live data, render it, inspect the result, and make targeted repairs.

HTML pages live inside the same report as native chart pages. They use the report's connections, model, instructions, reference files, conversation, filters, and access policy.

Their layout can respond to available width and scroll. Native report pages have a separate saved canvas size; that size does not constrain HTML layouts.

Create an HTML page

1. Open a report with editing access.
2. In the page list, find HTML Pages and click New HTML page, or ask the assistant to create one.
3. Describe the layout, calculations, audience, and reference material in Data Chat.
4. Follow the assistant's saves, execution checks, and browser previews.
5. Open the resulting page and inspect its visuals and controls.

Create an HTML page named Customer Health. Use the current model and
the report's reference template. Include live summary cards, trends,
a segment comparison, and a searchable account table. Render the
complete page and fix query, JavaScript, and layout issues.

A page can have a distinctive visual design without giving its browser code unrestricted access to the underlying source.

Understand page composition

An HTML page has a layout and a set of independently registered visuals. Each live chart, KPI, narrative, or table has its own identity and data bindings. Decorative headings and backgrounds can stay in the page layout.

<main class="report">
  <header>
    <h1>Operations overview</h1>
    <p>Current performance and supporting detail</p>
  </header>
  <section data-unity-visual="revenue-kpi"></section>
  <section data-unity-visual="monthly-trend"></section>
  <section data-unity-visual="order-details"></section>
</main>

The referenced visuals must be registered on the page. The layout alone does not define their data or appearance. See HTML visuals and data for the complete contract.

Use the page controls

Unity supplies the selection outline, inspection drawer, filter controls, and loading feedback. These remain available around the custom page.

Edit source directly

1. Click Source.
2. Choose Page layout or a registered visual under Component.
3. For a visual, choose HTML, CSS, or JavaScript under Source.
4. Edit or use Copy source.
5. Save the change and review the rendered result.

Drafts remain available while you switch components. A conflict warns that the underlying source changed elsewhere; copy the draft before using Reload latest.

A save enters history. Query or registration validation can reject a proposed change before it is saved. A JavaScript rendering error can occur after a valid save and should be repaired or restored from history.

Render and test the page

The assistant has two complementary checks:

After changing displayed HTML content, the assistant should inspect the resulting preview, including relevant sections below the fold. A screenshot can reveal clipping, unreadable text, empty charts, and spacing problems that a successful data read cannot.

Preview width supports 320–1,920 pixels and height supports 240–1,200 pixels. With width and height set to null, the preview uses the last known editor size when available, otherwise 1,280 × 900. Scrolling captures additional regions.

A test can inspect DOM elements and exercise page controls. For example, this is an illustrative test function body for a page containing a registered order-details visual:

const table = document.querySelector(
  '[data-unity-visual="order-details"] table'
);
check("Detail table rendered", Boolean(table));
record("Rendered table count", document.querySelectorAll("table").length);

Such a check establishes that a table exists. It does not establish that the underlying business calculation is correct.

Isolated tests do not save source, change report history, or persist runtime filter selections. Check host navigation, permissions, and cross-visual interactions in the live workspace too.

Refine a reference design

Attach an example HTML file, PDF, slide deck, workbook, or image. Ask the assistant to inspect its source and preview, reuse original image assets, and adapt the design to live visuals.

Compare reference and result at comparable viewport sizes. The reference's sample business numbers should not become hardcoded “live” metrics.

See Reference files for supported formats, report-wide reuse, and preview limits.

Appearance and sandbox

The authored source controls the page's appearance. You can use responsive CSS, local variables, and prefers-color-scheme. A page can provide its own theme control through supported renderer helpers; Unity does not impose a separate HTML theme picker in the report header.

HTML runs in a sandboxed iframe. Inline browser code, SVG, canvas, and ordinary DOM APIs are available. External fetches, CDN scripts, remote imports, parent-page access, cookies, and browser storage are unavailable. Use Unity's datasets and report assets instead.

HTML source is browser-ready code, not a React or TypeScript build project.

Let people save text into a page

Mark an element data-unity-writable and give the page a script that calls unity.save(element, text) to let people type into it, for example a decision typed while presenting. Only people with Edit content or Edit on the page (or on the whole report) can save; View people and public links cannot, and Unity tells them. A save is a normal version of the page: attributed to the person in Version history, visible to everyone viewing the page within seconds, and restorable by editors. The text is stored and shown as plain text. See Edit content for giving access, and the authoring contract in the agent guide for the page API (unity.canSave(), unity.save() and its error codes).

Restore a page version

Open Version history, select a version and choose Restore this page. Unity shows what the restore changes first; then choose Restore. A page restore covers the page's HTML, visual registrations, datasets and their queries, and the page's filters; the data model, other pages and access settings stay as they are.

The restore is itself a new version, so you can restore back. See Version history for whole-report restores and deleted pages.

Troubleshoot rendering