excalidraw/dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx

# ref
<pre>
<a href="https://reactjs.org/docs/refs-and-the-dom.html#creating-refs">createRef</a> &#124; <a href="https://reactjs.org/docs/hooks-reference.html#useref">useRef</a> &#124; <a href="https://reactjs.org/docs/refs-and-the-dom.html#callback-refs">callbackRef</a> &#124; <br/>&#123; current: &#123; readyPromise: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/utils.ts#L460">resolvablePromise</a> } }
</pre>

You can pass a `ref` when you want to access some excalidraw APIs. We expose the below APIs:

| API | Signature | Usage |
| --- | --- | --- |
| ready | `boolean` | This is set to true once Excalidraw is rendered |
| [readyPromise](#readypromise) | `function` | This promise will be resolved with the api once excalidraw has rendered. This will be helpful when you want do some action on the host app once this promise resolves. For this to work you will have to pass ref as shown [here](#readypromise) |
| [updateScene](#updatescene) | `function` | updates the scene with the sceneData |
| [updateLibrary](#updatelibrary) | `function` | updates the scene with the sceneData |
| [addFiles](#addfiles) | `function` | add files data to the appState |
| [resetScene](#resetscene) | `function` | Resets the scene. If `resetLoadingState` is passed as true then it will also force set the loading state to false. |
| [getSceneElementsIncludingDeleted](#getsceneelementsincludingdeleted) | `function` | Returns all the elements including the deleted in the scene |
| [getSceneElements](#getsceneelements) | `function` | Returns all the elements excluding the deleted in the scene |
| [getAppState](#getappstate) | `function` | Returns current appState |
| [history](#history) | `object` | This is the history API. `history.clear()` will clear the history |
| [scrollToContent](#scrolltocontent) | `function` | Scroll the nearest element out of the elements supplied to the center. Defaults to the elements on the scene. |
| [refresh](#refresh) | `function` | Updates the offsets for the Excalidraw component so that the coordinates are computed correctly (for example the cursor position). |
| [setToast](#settoast) | `function` | This API can be used to show the toast with custom message. |
| [id](#id) | `string` | Unique ID for the excalidraw component. |
| [getFiles](#getfiles) | `function` | This API can be used to get the files present in the scene. |
| [setActiveTool](#setactivetool) | `function` | This API can be used to set the active tool |
| [setCursor](#setcursor) | `function` | This API can be used to set customise the mouse cursor on the canvas |
| [resetCursor](#resetcursor) | `function` | This API can be used to reset to default mouse cursor on the canvas |
| [toggleMenu](#togglemenu) | `function` | Toggles specific menus on/off |

## readyPromise

<pre>
  const excalidrawRef = &#123; current:&#123; readyPromise:
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/utils.ts#L460">
    &nbsp;resolvablePromise
  </a>
  &nbsp;&#125; &#125;
</pre>

Since plain object is passed as a `ref`, the `readyPromise` is resolved as soon as the component is mounted. Most of the time you will not need this unless you have a specific use case where you can't pass the `ref` in the react way and want to do some action on the host when this promise resolves.

```jsx showLineNumbers
const resolvablePromise = () => {
  let resolve;
  let reject;
  const promise = new Promise((_resolve, _reject) => {
    resolve = _resolve;
    reject = _reject;
  });
  promise.resolve = resolve;
  promise.reject = reject;
  return promise;
};

const App = () => {
  const excalidrawRef = useMemo(
    () => ({
      current: {
        readyPromise: resolvablePromise(),
      },
    }),
    [],
  );

  useEffect(() => {
    excalidrawRef.current.readyPromise.then((api) => {
      console.log("loaded", api);
    });
  }, [excalidrawRef]);
  return (
    <div style={{ height: "500px" }}>
      <Excalidraw ref={excalidrawRef} />
    </div>
  );
};
```

## updateScene

<pre>
  (scene:{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L339">
    sceneData
  </a>
  ) => void
</pre>

You can use this function to update the scene with the sceneData. It accepts the below attributes.

| Name | Type | Description |
| --- | --- | --- |
| `elements` | [`ImportedDataState["elements"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L38) | The `elements` to be updated in the scene |
| `appState` | [`ImportedDataState["appState"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L39) | The `appState` to be updated in the scene. |
| `collaborators` | <code>Map<string, <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L37">Collaborator></a></code> | The list of collaborators to be updated in the scene. |
| `commitToHistory` | `boolean` | Implies if the `history (undo/redo)` should be recorded. Defaults to `false`. |

```jsx live
function App() {
  const updateScene = () => {
    const sceneData = {
      elements: [
        {
          type: "rectangle",
          version: 141,
          versionNonce: 361174001,
          isDeleted: false,
          id: "oDVXy8D6rom3H1-LLH2-f",
          fillStyle: "hachure",
          strokeWidth: 1,
          strokeStyle: "solid",
          roughness: 1,
          opacity: 100,
          angle: 0,
          x: 100.50390625,
          y: 93.67578125,
          strokeColor: "#c92a2a",
          backgroundColor: "transparent",
          width: 186.47265625,
          height: 141.9765625,
          seed: 1968410350,
          groupIds: [],
          boundElements: null,
          locked: false,
          link: null,
          updated: 1,
          roundness: {
            type: 3,
            value: 32,
          },
        },
      ],
      appState: {
        viewBackgroundColor: "#edf2ff",
      },
    };
    excalidrawAPI.updateScene(sceneData);
  };
  const [excalidrawAPI, setExcalidrawAPI] = useState(null);
  return (
    <div style={{ height: "500px" }}>
      <p style={{ fontSize: "16px" }}> Click to update the scene</p>
      <button className="custom-button" onClick={updateScene}>Update Scene</button>
      <Excalidraw ref={(api) => setExcalidrawAPI(api)} />
    </div>
  );
}
```

### updateLibrary

<pre>
  (opts: &#123; <br /> libraryItems:{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L249">
    LibraryItemsSource
  </a>
  ;<br /> merge?: boolean; <br /> prompt?: boolean;
  <br /> openLibraryMenu?: boolean;
  <br /> defaultStatus?: "unpublished" | "published"; <br /> &#125;) => Promise&lt;
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L246">
    LibraryItems
  </a>
  &gt;
</pre>

You can use this function to update the library. It accepts the below attributes.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `libraryItems` | [LibraryItemsSource](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L249) | \_ | The `libraryItems` to be replaced/merged with current library |
| `merge` | boolean | `false` | Whether to merge with existing library items. |
| `prompt` | boolean | `false` | Whether to prompt user for confirmation. |
| `openLibraryMenu` | boolean | `false` | Keep the library menu open after library is updated. |
| `defaultStatus` | <code>"unpublished" &#124; "published"</code> | `"unpublished"` | Default library item's `status` if not present. |

```tsx live
function App() {
  const [excalidrawAPI, setExcalidrawAPI] = useState(null);

  useEffect(() => {
    if (!excalidrawAPI) {
      return;
    }
    // to open the library sidebar
    excalidrawAPI.updateScene({ appState: { openSidebar: "library" } });
  }, [excalidrawAPI]);

  return (
    <div style={{ height: "500px" }}>
      <p style={{ fontSize: "16px" }}> Click to update the library items</p>
      <button className="custom-button"
        onClick={() => {
          const libraryItems = [
            {
              status: "published",
              id: "1",
              created: 1,
              elements: initialData.libraryItems[1],
            },
            {
              status: "unpublished",
              id: "2",
              created: 2,
              elements: initialData.libraryItems[1],
            },
          ];
          excalidrawAPI.updateLibrary({
            libraryItems,
            openLibraryMenu: true

          });
         
        }}
      >
        Update Library
      </button>
      <Excalidraw
        ref={(api) => setExcalidrawAPI(api)}
        // initial data retrieved from https://github.com/excalidraw/excalidraw/blob/master/dev-docs/src/initialData.js
        initialData={{
          libraryItems: initialData.libraryItems,
          appState: { openSidebar: "library" },
        }}
      />
    </div>
  );
}
```

### addFiles

<pre>
  (files:{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L59">
    BinaryFileData
  </a>
  ) => void
</pre>

Adds supplied files data to the `appState.files` cache on top of existing files present in the cache.

## resetScene

```tsx
(opts?: { resetLoadingState: boolean }) => void
```

Resets the scene. If `resetLoadingState` is passed as true then it will also force set the loading state to false.

## getSceneElementsIncludingDeleted

<pre>
  () =>{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">
    ExcalidrawElement[]
  </a>
</pre>

Returns all the elements including the deleted in the scene.

## getSceneElements

<pre>
  () => NonDeleted&#60;
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">
    ExcalidrawElement
  </a>
  []&#62;
</pre>

Returns all the elements excluding the deleted in the scene

## getAppState

<pre>
  () =>{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95">
    AppState
  </a>
</pre>

Returns current appState.

## history

```tsx
{
  clear: () => void
}
```

This is the history API. history.clear() will clear the history.

## scrollToContent

<pre>
  (target?:{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">
    ExcalidrawElement
  </a>{" "}
  &#124;{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">
    ExcalidrawElement
  </a>
  []) => void
</pre>

Scroll the nearest element out of the elements supplied to the center. Defaults to the elements on the scene.

## refresh

```tsx
() => void
```

Updates the `offsets` for the `Excalidraw` component so that the coordinates are computed correctly (for example the cursor position).

You don't have to call this when the position is changed on page scroll or when the excalidraw container resizes (we handle that ourselves).

For any other cases if the position of excalidraw is updated (example due to scroll on parent container and not page scroll) you should call this API.

## setToast

This API can be used to show the toast with custom message.

```tsx
({ message: string, closable?:boolean,duration?:number 
  } | null) => void
```

| Attribute | type | Description |
| --- | --- | --- |
| message | string | The message to be shown on the toast. |
| closable | boolean | Indicates whether to show the closable button on toast to dismiss the toast. |
| duration | number | Determines the duration after which the toast should auto dismiss. To prevent autodimiss you can pass `Infinity`. |

To dismiss an existing toast you can simple pass `null`

```js
setToast(null);
```

## id

The unique id of the excalidraw component. This can be used to identify the excalidraw component, for example importing the library items to the excalidraw component from where it was initiated when you have multiple excalidraw components rendered on the same page as shown in [multiple excalidraw demo](https://codesandbox.io/s/multiple-excalidraw-k1xx5).

## getFiles

<pre>
  () =>{" "}
  <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L82">
    files
  </a>
</pre>

This API can be used to get the files present in the scene. It may contain files that aren't referenced by any element, so if you're persisting the files to a storage, you should compare them against stored elements.

## setActiveTool

This API has the below signature. It sets the `tool` passed in param as the active tool.


<pre>
(tool: <br/>  &#123; type: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/shapes.tsx#L15">SHAPES</a>[number]["value"]&#124; "eraser" &#125; &#124;<br/>  &#123; type: "custom"; customType: string &#125;) => void
</pre>

## setCursor

This API can be used to customise the mouse cursor on the canvas and has the below signature.   
It sets the mouse cursor to the cursor passed in param.

```tsx
(cursor: string) => void
```

## toggleMenu

```tsx
(type: "library" | "customSidebar", force?: boolean) => boolean;
```

This API can be used to toggle a specific menu (currently only the sidebars), and returns whether the menu was toggled on or off. If the `force` flag passed, it will force the menu to be toggled either on/off based on the `boolean` passed.

This API is especially useful when you render a custom sidebar using [`renderSidebar`](#rendersidebar) prop, and you want to toggle it from your app based on a user action.

## resetCursor

```tsx
() => void
```

This API can be used to reset to default mouse cursor.