Skip to content

Virtual whiteboard for sketching hand-drawn like diagrams

feat: support `ExcalidrawElement.customData` (#5592)

David Luzarb914ad41fc61
diff --git a/src/data/restore.ts b/src/data/restore.ts
index 24bfca79f7..ce7bc434c8 100644
--- a/src/data/restore.ts
+++ b/src/data/restore.ts
@@ -67,13 +67,14 @@ const getFontFamilyByName = (fontFamilyName: string): FontFamilyValues => {
};
const restoreElementWithProperties = <
- T extends ExcalidrawElement,
- K extends Pick<T, keyof Omit<Required<T>, keyof ExcalidrawElement>>,
->(
- element: Required<T> & {
+ T extends Required<Omit<ExcalidrawElement, "customData">> & {
+ customData?: ExcalidrawElement["customData"];
/** @deprecated */
boundElementIds?: readonly ExcalidrawElement["id"][];
},
+ K extends Pick<T, keyof Omit<Required<T>, keyof ExcalidrawElement>>,
+>(
+ element: T,
extra: Pick<
T,
// This extra Pick<T, keyof K> ensure no excess properties are passed.
@@ -115,6 +116,10 @@ const restoreElementWithProperties = <
locked: element.locked ?? false,
};
+ if ("customData" in element) {
+ base.customData = element.customData;
+ }
+
return {
...base,
...getNormalizedDimensions(base),
diff --git a/src/element/types.ts b/src/element/types.ts
index 0834efd6c7..adbeba334b 100644
--- a/src/element/types.ts
+++ b/src/element/types.ts
@@ -56,6 +56,7 @@ type _ExcalidrawElementBase = Readonly<{
updated: number;
link: string | null;
locked: boolean;
+ customData?: Record<string, any>;
}>;
export type ExcalidrawSelectionElement = _ExcalidrawElementBase & {
diff --git a/src/packages/excalidraw/CHANGELOG.md b/src/packages/excalidraw/CHANGELOG.md
index 2e6e043aca..d69f64618b 100644
--- a/src/packages/excalidraw/CHANGELOG.md
+++ b/src/packages/excalidraw/CHANGELOG.md
@@ -15,9 +15,11 @@ Please add the latest change on the top under the correct section.
### Excalidraw API
+- Added support for storing [`customData`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#storing-custom-data-to-excalidraw-elements) on Excalidraw elements [#5592].
+
#### Breaking Changes
-- `setToastMessage` API is now renamed to `setToast` API and the function signature is also updated [#5427](https://github.com/excalidraw/excalidraw/pull/5427). You can also pass `duration` and `closable` attributes along with `message`.
+- `setToastMessage` API is now renamed to `setToas○t` API and the function signature is also updated [#5427](https://github.com/excalidraw/excalidraw/pull/5427). You can also pass `duration` and `closable` attributes along with `message`.
## 0.12.0 (2022-07-07)
diff --git a/src/packages/excalidraw/README.md b/src/packages/excalidraw/README.md
index 6757ca9b41..2002906a6a 100644
--- a/src/packages/excalidraw/README.md
+++ b/src/packages/excalidraw/README.md
@@ -470,6 +470,14 @@ This helps to load Excalidraw with `initialData`. It must be an object or a [pro
You might want to use this when you want to load excalidraw with some initial elements and app state.
+#### Storing custom data on Excalidraw elements
+
+Beyond attributes that Excalidraw elements already support, you can store custom data on each element in a `customData` object. The type of the attribute is [`Record<string, any>`](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L59) and is optional.
+
+You can use this to add any extra information you need to keep track of.
+
+You can add `customData` to elements when passing them as `initialData`, or using [`updateScene`](#updateScene)/[`updateLibrary`](#updateLibrary) afterwards.
+
#### `ref`
You can pass a `ref` when you want to access some excalidraw APIs. We expose the below APIs: