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.

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, query editor, 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 three 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 successful SQL execution 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.

Restore a page version

Open Page history, select a version, and choose Restore version or Restore v…. Restoration covers the page's HTML, visual registrations, and queries.

Current page names, report/page filters, and access settings stay in place. The restoration itself can be undone. See Change history for conflicts and scope.

Troubleshoot rendering