Restore Utilities

restoreAppState

Signature

restoreAppState(appState: ImportedDataState["appState"],
  localAppState: Partial<AppState> | null): AppState

How to use

import { restoreAppState } from "@excalidraw/excalidraw";

This function will make sure all the keys have appropriate values in appState and if any key is missing, it will be set to its default value.

When localAppState is supplied, it's used in place of values that are missing (undefined) in appState instead of the defaults.
Use this as a way to not override user's defaults if you persist them. You can pass null / undefined if not applicable.

restoreElements

Signature

restoreElements( elements: ImportedDataState["elements"],
  localElements: ExcalidrawElement[] | null | undefined): ExcalidrawElement[],
  opts: { refreshDimensions?: boolean, repairBindings?: boolean }
)

Prop	Type	Description
elements	ImportedDataState["elements"]	The elements to be restored
localElements	ExcalidrawElement[] | null | undefined	When localElements are supplied, they are used to ensure that existing restored elements reuse version (and increment it), and regenerate versionNonce.
opts	Object	The extra optional parameter to configure restored elements

localElements

When localElements are supplied, they are used to ensure that existing restored elements reuse version (and increment it), and regenerate versionNonce.
Use this when you import elements which may already be present in the scene to ensure that you do not disregard the newly imported elements if you're using element version to detect the update

opts

The extra optional parameter to configure restored elements. It has the following attributes

Prop	Type	Description
refreshDimensions	boolean	Indicates whether we should also recalculate text element dimensions. Since this is a potentially costly operation, you may want to disable it if you restore elements in tight loops, such as during collaboration.
repairBindings	boolean	Indicates whether the bindings for the elements should be repaired. This is to make sure there are no containers with non existent bound text element id and no bound text elements with non existent container id.

How to use

import { restoreElements } from "@excalidraw/excalidraw";

This function will make sure all properties of element is correctly set and if any attribute is missing, it will be set to its default value.

Parameter refreshDimensions indicates whether we should also recalculate text element dimensions. Defaults to false. Since this is a potentially costly operation, you may want to disable it if you restore elements in tight loops, such as during collaboration.

restore

Signature

restore( data: ImportedDataState,
  localAppState: Partial<AppState> | null | undefined,
  localElements: ExcalidrawElement[] | null | undefined
): DataState
opts: { refreshDimensions?: boolean, repairBindings?: boolean }
)

See restoreAppState() about localAppState, and restoreElements() about localElements.

How to use

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 a combination of restoreElements and restoreAppState.

restoreLibraryItems

Signature

restoreLibraryItems(libraryItems: ImportedDataState["libraryItems"],
  defaultStatus: "published" | "unpublished")

How to use

import { restoreLibraryItems } from "@excalidraw/excalidraw";

restoreLibraryItems(libraryItems, "unpublished");

This function normalizes library items elements, adding missing values when needed.