Display and Export

The same composed chart can display as a live notebook widget or export through one unified static API covering PNG, JPEG, WebP, SVG, PDF, and standalone interactive HTML.

Leave the chart as the final cell expression, or return its widget explicitly:

show() returns the live notebook widget; it does not launch a desktop window. See Notebooks for callbacks, binary comms, and supported hosts.

to_image() returns bytes; write_image() writes a file atomically and infers the format from the extension:

engine="auto" (the default) is deterministic: every format uses the native path unless custom_css is passed, which forces Chromium because utility-class CSS needs a real CSS engine. engine=Engine.chromium opts into browser CSS, font, and WebGL fidelity for any format except SVG. Native exports never install or launch a browser; when Chromium is requested but not found, the error names XY_BROWSER and the supported browsers.

background accepts "auto" (each renderer's default backdrop: opaque white for raster/browser output, transparent for SVG), any CSS color, or "transparent":

JPEG has no alpha channel, so background="transparent" is rejected there rather than silently flattened. An explicit color (or "transparent") replaces the chart's theme backgrounds — both theme(background=...) and theme(plot_background=...) — painting one backdrop consistently in every format (raster canvas, SVG/PDF rect, browser page); "auto" keeps the theme paints untouched.

scale is the device-pixel-ratio for raster formats and is ignored by SVG/PDF, which are resolution-independent. A 300×200 chart at scale=2 produces a 600×400 raster.

xy.export_config describes export behavior as part of the chart — no I/O happens at build time. It governs the modebar's download menu and provides defaults for the Python export calls:

The browser modebar shows the client-safe subset (png, jpeg, webp, svg, csv) with the same filename, scale, background, and quality semantics as the Python exporters; pdf/html entries affect Python-side defaults only. formats=[] hides the download menu entirely. Standalone HTML exports keep the full download menu working without any Python kernel attached, and Reflex charts inherit the same spec-driven configuration. Explicit arguments to to_image()/write_image() always override the declarative defaults.

HTML export is self-contained: it includes the chart spec, binary data, and bundled render client. It keeps zoom, pan, hover, selection, and built-in chart chrome and does not need a browser or network connection at export time.

Pass custom_css= to include author CSS for chrome classes and tokens in the exported document. Standalone HTML uses inline scripts and styles by design; read Serving, CSP, and offline use before placing it inside a stricter application policy.

to_png(), to_svg(), and to_html() remain supported with their existing signatures:

The default PNG engine is XY's browser-free native rasterizer; set optimize=True to spend more time producing a smaller native PNG. SVG export is browser-free and screen-bounded: long lines are decimated before vector generation, while density and heatmap representations embed compact raster data where appropriate. For Chromium exports, XY searches for Chrome, Chromium, Edge, or chrome-headless-shell; set XY_BROWSER to select an executable explicitly. The browser sandbox is enabled by default; disable it only for trusted input in an environment where the caller accepts that risk.

Use one batch call instead of exporting in a loop — formats can be mixed, and every Chromium-resolved file in the batch shares a single browser session:

Per-file formats come from the extensions (formats= overrides them), and writes are atomic per file. With the native engine the same call loops the millisecond-fast browser-free renderers.

Facet grids support the same format matrix as single charts:

Native raster output composes the browser-free panel renders (the grid title strip is omitted there — the native rasterizer has no free-standing text path); SVG/PDF compose the vector panels, title included; Chromium renders the full HTML grid.

Interactive chart width and height accept positive pixel integers. Ordinary charts also accept percentages such as width="100%"; the parent must define a height when using height="100%". Static raster and facet output should use explicit dimensions for deterministic results; fluid ("100%") charts fall back to 800×500 at export time. Exports are deterministic byte-for-byte for identical figures and options — no timestamps, transient hover chrome, or nondeterministic ids are embedded.