Skip to content

Virtual whiteboard for sketching hand-drawn like diagrams

feat: Export API's to export the drawing to canvas, svg and blob (#3258)

Aakansha Doshiedc62c550adc
diff --git a/src/packages/excalidraw/CHANGELOG.md b/src/packages/excalidraw/CHANGELOG.md
index ec8bd23bff..a949b1d638 100644
--- a/src/packages/excalidraw/CHANGELOG.md
+++ b/src/packages/excalidraw/CHANGELOG.md
@@ -18,6 +18,7 @@ Please add the latest change on the top under the correct section.
### Features
+- Export API to export the drawing to canvas, svg and blob [#3258](https://github.com/excalidraw/excalidraw/pull/3258). For more info you can check the [readme](https://github.com/excalidraw/excalidraw/tree/master/src/packages/excalidraw/README.md#user-content-export-utils)
- Add a `theme` prop to indicate Excalidraw's theme. [#3228](https://github.com/excalidraw/excalidraw/pull/3228). When this prop is passed, the theme is fully controlled by host app.
- Support `libraryReturnUrl` prop to indicate what URL to install libraries to [#3227](https://github.com/excalidraw/excalidraw/pull/3227).
diff --git a/src/packages/excalidraw/README.md b/src/packages/excalidraw/README.md
index 6cd8b652ef..26474b5202 100644
--- a/src/packages/excalidraw/README.md
+++ b/src/packages/excalidraw/README.md
@@ -635,3 +635,93 @@ import { restore } from "@excalidraw/excalidraw";
```
This function makes sure elements and state is set to appropriate values and set to default value if not present. It is combination of [restoreElements](#restoreElements) and [restoreAppState](#restoreAppState)
+
+**_The below APIs will be available in [next version](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/CHANGELOG.md#unreleased)_**
+
+<details id="export-utils">
+<summary><strong>Export utilities</strong></summary>
+
+#### `exportToCanvas`
+
+**_Signature_**
+
+<pre
+>exportToCanvas({
+ elements,
+ appState
+ getDimensions,
+}: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L10">ExportOpts</a>
+</pre>
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types) | | The elements to be exported to canvas |
+| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L12) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene |
+| getDimensions | `(width: number, height: number) => {width: number, height: number, scale: number)` | `(width, height) => ({ width, height, scale: 1 })` | A function which returns the width, height and scale with which canvas is to be exported. |
+
+**How to use**
+
+```js
+import { exportToCanvas } from "@excalidraw/excalidraw";
+```
+
+This function returns the canvas with the exported elements, appState and dimensions.
+
+#### `exportToBlob`
+
+**_Signature_**
+
+<pre>
+exportToBlob(
+ opts: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L10">ExportOpts</a> & {
+ mimeType?: string,
+ quality?: number;
+})
+</pre>
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| opts | | | This param is passed to `exportToCanvas`. You can refer to [`exportToCanvas`](#exportToCanvas) |
+| mimeType | string | "image/png" | Indicates the image format |
+| quality | number | 0.92 | A value between 0 and 1 indicating the [image quality](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob#parameters). Applies only to `image/jpeg`/`image/webp` MIME types. |
+
+**How to use**
+
+```js
+import { exportToBlob } from "@excalidraw/excalidraw";
+```
+
+Returns a promise which resolves with a [blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob). It internally uses [canvas.ToBlob](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toBlob).
+
+#### `exportToSvg`
+
+**_Signature_**
+
+<pre>
+exportToSvg({
+ elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>,
+ appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42">AppState</a>,
+ exportPadding?: number,
+ metadata?: string,
+}
+</pre>
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78) | | The elements to exported as svg |
+| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene |
+| exportPadding | number | 10 | The padding to be added on canvas |
+| metadata | string | '' | The metadata to be embedded in svg |
+
+This function returns a svg with the exported elements.
+
+##### Additional attributes of appState for `export\*` APIs
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| exportBackground | boolean | true | Indicates whether background should be exported |
+| viewBackgroundColor | string | #fff | The default background color |
+| shouldAddWatermark | boolean | false | Indicates whether watermark should be exported |
+| exportWithDarkMode | boolean | false | Indicates whether to export with dark mode |
+
+</details>
diff --git a/src/packages/excalidraw/index.tsx b/src/packages/excalidraw/index.tsx
index 8c1e3b1f13..868cf47cff 100644
--- a/src/packages/excalidraw/index.tsx
+++ b/src/packages/excalidraw/index.tsx
@@ -112,3 +112,8 @@ export {
} from "../../element";
export { defaultLang, languages } from "../../i18n";
export { restore, restoreAppState, restoreElements } from "../../data/restore";
+export {
+ exportToCanvas,
+ exportToBlob,
+ exportToSvg,
+} from "../../packages/utils";
diff --git a/src/packages/utils.ts b/src/packages/utils.ts
index 25731ef66a..0f4c1c402e 100644
--- a/src/packages/utils.ts
+++ b/src/packages/utils.ts
@@ -6,10 +6,11 @@ import { getDefaultAppState } from "../appState";
import { AppState } from "../types";
import { ExcalidrawElement } from "../element/types";
import { getNonDeletedElements } from "../element";
+import { restore } from "../data/restore";
type ExportOpts = {
elements: readonly ExcalidrawElement[];
- appState?: Omit<AppState, "offsetTop" | "offsetLeft">;
+ appState?: Partial<Omit<AppState, "offsetTop" | "offsetLeft">>;
getDimensions: (
width: number,
height: number,
@@ -18,17 +19,22 @@ type ExportOpts = {
export const exportToCanvas = ({
elements,
- appState = getDefaultAppState(),
+ appState,
getDimensions = (width, height) => ({ width, height, scale: 1 }),
}: ExportOpts) => {
+ const { elements: restoredElements, appState: restoredAppState } = restore(
+ { elements, appState },
+ null,
+ );
+ const {
+ exportBackground,
+ viewBackgroundColor,
+ shouldAddWatermark,
+ } = restoredAppState;
return _exportToCanvas(
- getNonDeletedElements(elements),
- { ...appState, offsetTop: 0, offsetLeft: 0 },
- {
- exportBackground: appState.exportBackground ?? true,
- viewBackgroundColor: appState.viewBackgroundColor ?? "#FFF",
- shouldAddWatermark: appState.shouldAddWatermark ?? false,
- },
+ getNonDeletedElements(restoredElements),
+ { ...restoredAppState, offsetTop: 0, offsetLeft: 0 },
+ { exportBackground, viewBackgroundColor, shouldAddWatermark },
(width: number, height: number) => {
const canvas = document.createElement("canvas");
const ret = getDimensions(width, height);
@@ -81,8 +87,12 @@ export const exportToSvg = ({
exportPadding?: number;
metadata?: string;
}): SVGSVGElement => {
- return _exportToSvg(getNonDeletedElements(elements), {
- ...appState,
+ const { elements: restoredElements, appState: restoredAppState } = restore(
+ { elements, appState },
+ null,
+ );
+ return _exportToSvg(getNonDeletedElements(restoredElements), {
+ ...restoredAppState,
exportPadding,
metadata,
});