Skip to main content

Embed Vizly Charts in Any HTML Page

Vizly does not force you into a specific framework. Charts export as self-contained HTML with local, vendored ECharts, ready to drop into any page: static sites, server-rendered apps, CMS pages, or iframes.

Self-contained single chart​

to_html() returns a full HTML document. Open it directly, save it, or serve it as-is.

import vizly as vz

data = [{"date": "2026-01-01", "revenue": 42}, {"date": "2026-01-02", "revenue": 48}]
chart = vz.line(data, x="date", y="revenue", title="Revenue")

html = chart.to_html()          # full document, ECharts inlined
chart.render("revenue.html")    # or write it to a file

Fragments inside an existing page​

If your page already exists, render just the chart markup with fragment=True. The fragment omits the page shell.

fragment = chart.to_html(fragment=True)

Then paste the fragment into any container:

<div class="chart">
  <!-- paste the fragment here -->
</div>

Loading assets once for several charts​

For multiple charts on one page, load the ECharts assets once in the head, then embed each chart as a fragment that reuses them. This keeps the page small when you have several charts.

from vizly.integrations import assets_html, chart_html

charts = [
    vz.bar([{"region": "Northeast", "sales": 86}], x="region", y="sales", title="Sales"),
    vz.pie([{"name": "Enterprise", "value": 34}], names="name", values="value", title="Mix"),
]

head = assets_html(charts=charts)              # <link>/<script> tags for the head
body = "".join(chart_html(c, fragment=True, include_assets=False) for c in charts)
<!DOCTYPE html>
<html>
<head>
  {{ head|safe }}
</head>
<body>
  {{ body|safe }}
</body>
</html>

A multi-chart dashboard blob​

dashboard_html() returns one HTML document containing several charts with a single ECharts load. It is the fastest way to produce a complete dashboard page.

from vizly.integrations import dashboard_html

html = dashboard_html(charts, title="Operations dashboard")

Embedding in an iframe​

Charts render fine inside iframes. If the parent page needs to hear chart click events, pass message_origin to restrict postMessage to a specific parent origin.

fragment = chart.to_html(
    fragment=True,
    message_origin="https://app.example.com",
)

Then embed the fragment in an iframe in the parent app. The parent listens for the vizly:event payload to drive drilldowns and linked views.

Live updates without reload​

After a chart is embedded, push new data without reloading the page. Capture the chart id from the embed, then inject the live update script.

# Initial embed carries an id, e.g. from chart_html
embed = chart_html(chart, fragment=True)

# Later, when data changes:
chart.set_data(new_table)
update_script = chart.live_update_script(chart.id)
# Inject this <script> wherever the chart lives

In the browser, the same update is possible with the global registry:

window.__vizly[chartId].setOption({ series: [{ data: [...] }] });

Tips​

TipDetail
Start self-containedto_html() is a full document with no external assets. Open it anywhere.
Fragment for existing pagesUse fragment=True to get only the chart markup.
Assets once for many chartsLoad assets_html() in the head, then use fragments with include_assets=False.
Constrain message originSet message_origin when embedding in iframes so events only reach your own app.
Update liveUse set_data plus live_update_script to refresh a chart without reloading ECharts.