Image Export

useImageExport() renders the current diagram to an image (PNG, JPEG, WebP, or SVG) that you can download as a file or read as a data URL.

Open Sandbox

Pick an output format in the toolbar's toggle group, then click Export diagram to render the whole graph. To export just part of it, drag across the canvas to rubber-band a region. Either way the result lands in the preview. One export hook handles both cases: you pass it the format and an optional region as options.

The export hook

useImageExport() returns a pair: an export function you call to produce the image, and a state object that tracks the attempt. You set what to export (the format, an optional region, sizing) through the hook's options. The export function itself takes only an optional file name (downloadAs). So you can keep the format in state and let the hook re-bind whenever it changes, the way the demo does with its toggle group:

const [format, setFormat] = useState('image/png');
const [exportImage, state] = useImageExport({ type: format });

If you prefer stable handlers, hard-code the type and create one hook per format instead.

Call it from a component inside your <GraphProvider> (or <Diagram>). It resolves the diagram's paper automatically.

Download a file or read a data URL

The export function resolves to the image as a data URL. Pass downloadAs to also save it as a file:

await exportPng({ downloadAs: 'diagram' }); // saves diagram.png and resolves the data URL
const url = await exportPng();              // no file, just the data URL

Omit downloadAs when you want to handle the result yourself: render it in an <img>, upload it, or store it. That is what the demo does to fill its preview.

Tracking export state

The state object reports a status ('idle', 'loading', 'success', or 'error') alongside isLoading / isSuccess / isError booleans, the resulting data, and any error. Use it to disable a control and show progress while an export is in flight, or to surface a failure:

const [exportPng, state] = useImageExport({ type: 'image/png' });

<button onClick={() => exportPng({ downloadAs: 'diagram' })} disabled={state.isLoading}>
  {state.isLoading ? 'Exporting…' : 'Export PNG'}
</button>

Choosing a format

Set the format with type, one of 'image/png', 'image/jpeg', 'image/webp', or 'image/svg+xml':

useImageExport({ type: 'image/webp' });

Tuning raster output

For the raster formats (PNG, JPEG, WebP), pass sizing and styling options to the hook:

useImageExport({
  type: 'image/png',
  padding: 10,             // margin around the content
  backgroundColor: '#fff', // fill behind the diagram
  quality: 0.92,           // JPEG / WebP compression (0-1)
});

By default the export scales to the screen's device pixel ratio, so it stays crisp on HiDPI displays. You rarely set the scale yourself. Pin an exact result with width and height, or scale it with size (a multiplier such as '2x'); setting either one steps the automatic scaling aside so it never distorts the size you asked for. Use area to export just a region of the diagram instead of the whole graph (see Export a region), and grid to include the paper grid. The hook also defaults to embedding fonts and copying computed styles, so the export matches the on-screen diagram.

These options pass through to JointJS+'s raster exporter. See the Raster format API for the full set.

SVG output

For 'image/svg+xml', the export resolves a data:image/svg+xml URL. Pass raw to get the serialized <svg>…</svg> markup string instead, which is useful for inlining the SVG or post-processing it:

const [exportSvg] = useImageExport({ type: 'image/svg+xml', raw: true });
const markup = await exportSvg(); // '<svg …>…</svg>'

An SVG export captures the diagram's vector content, not a rasterized snapshot, so the raster-only options (padding, backgroundColor, width / height, size, quality) don't apply. The paper's background is a CSS fill rather than part of the diagram, so it is left out too: an SVG export is transparent unless your cells draw their own background. SVG has its own options (area, grid, stylesheet, …). See the SVG format API.

HTML content stays browser-only

If your elements render HTML through <HTMLBox> or <HTMLHost>, that markup is embedded in the export as an SVG <foreignObject>. Browsers render it, so the file looks right in a web page or an <img> tag. Vector tools do not: Adobe Illustrator, Inkscape, and most SVG-to-PDF or rasterizing converters ignore <foreignObject> and skip those nodes, leaving the links and any native shapes but none of the HTML cells. For an SVG that holds up outside the browser, render the elements as native SVG instead of HTML.

Export a region

area is one of those hook options. Give it a rectangle and the export covers just that part of the graph instead of the whole thing. To let the user pick the rectangle, the demo pairs the hook with useRegion(): its startRectangleRegion() draws a rubber-band on a bare paper (no <Selection> or <Diagram> required) and resolves the rectangle the user dragged, or nothing if they cancel.

Because area lives in the hook options, the demo stores the drawn rectangle in state and exports it once the hook re-binds. That is what the blank-drag does in the demo above. useRegion() can also draw polygon and range regions when you need a shape other than a rectangle.

Targeting a specific paper

info

useImageExport() resolves the single default paper automatically. When your app renders more than one paper, pass a paper id or ref as the first argument: useImageExport(paperTarget, options).