From f472af04a975d0988f44b2fb3c7f5d1d3b2de121 Mon Sep 17 00:00:00 2001
From: barnabasmolnar <barnabas@excalidraw.com>
Date: Tue, 2 Jun 2026 19:06:32 +0200
Subject: [PATCH] [WIP] Initial implem of fade animating elements.

---
 .../with-nextjs/src/excalidrawWrapper.tsx     |   2 +
 .../components/ExampleApp.tsx                 |  60 +++++-
 .../with-script-in-browser/initialData.tsx    |  48 +++--
 packages/element/src/renderElement.ts         |  33 +++-
 packages/excalidraw/components/App.tsx        | 175 +++++++++++++++++-
 packages/excalidraw/index.tsx                 |   2 +
 packages/excalidraw/renderer/staticScene.ts   |  16 +-
 packages/excalidraw/scene/types.ts            |   4 +
 packages/excalidraw/types.ts                  |  10 +
 9 files changed, 327 insertions(+), 23 deletions(-)

diff --git a/examples/with-nextjs/src/excalidrawWrapper.tsx b/examples/with-nextjs/src/excalidrawWrapper.tsx
index fab4df6512..0fbf62af0f 100644
--- a/examples/with-nextjs/src/excalidrawWrapper.tsx
+++ b/examples/with-nextjs/src/excalidrawWrapper.tsx
@@ -1,4 +1,5 @@
 "use client";
+
 import * as excalidrawLib from "@excalidraw/excalidraw";
 import { Excalidraw } from "@excalidraw/excalidraw";
 
@@ -13,6 +14,7 @@ const ExcalidrawWrapper: React.FC = () => {
         appTitle={"Excalidraw with Nextjs Example"}
         useCustom={(api: any, args?: any[]) => {}}
         excalidrawLib={excalidrawLib}
+        showFadeDemo={true}
       >
         <Excalidraw />
       </App>
diff --git a/examples/with-script-in-browser/components/ExampleApp.tsx b/examples/with-script-in-browser/components/ExampleApp.tsx
index 294a11a58d..135dc74499 100644
--- a/examples/with-script-in-browser/components/ExampleApp.tsx
+++ b/examples/with-script-in-browser/components/ExampleApp.tsx
@@ -70,6 +70,7 @@ export interface AppProps {
   customArgs?: any[];
   children: React.ReactNode;
   excalidrawLib: typeof TExcalidraw;
+  showFadeDemo?: boolean;
 }
 
 export default function ExampleApp({
@@ -78,6 +79,7 @@ export default function ExampleApp({
   customArgs,
   children,
   excalidrawLib,
+  showFadeDemo = false,
 }: AppProps) {
   const {
     exportToCanvas,
@@ -116,6 +118,8 @@ export default function ExampleApp({
     {},
   );
   const [comment, setComment] = useState<Comment | null>(null);
+  const [hideAllForFadeDemo, setHideAllForFadeDemo] = useState(showFadeDemo);
+  const [fadeDemoNextIndex, setFadeDemoNextIndex] = useState(0);
 
   const initialStatePromiseRef = useRef<{
     promise: ResolvablePromise<ExcalidrawInitialDataState | null>;
@@ -178,7 +182,8 @@ export default function ExampleApp({
     const newElement = cloneElement(
       Excalidraw,
       {
-        excalidrawAPI: (api: ExcalidrawImperativeAPI) => setExcalidrawAPI(api),
+        onExcalidrawAPI: (api: ExcalidrawImperativeAPI | null) =>
+          setExcalidrawAPI(api),
         initialData: initialStatePromiseRef.current.promise,
         onChange: (
           elements: NonDeletedExcalidrawElement[],
@@ -208,6 +213,7 @@ export default function ExampleApp({
         onPointerDown,
         onScrollChange: rerenderCommentIcons,
         validateEmbeddable: true,
+        resolveRenderOpacity: hideAllForFadeDemo ? () => 0 : undefined,
       },
       <>
         {excalidrawAPI && (
@@ -664,6 +670,58 @@ export default function ExampleApp({
           >
             Reset Scene
           </button>
+          {showFadeDemo && (
+            <>
+              <button
+                onClick={() => {
+                  if (!excalidrawAPI) {
+                    return;
+                  }
+
+                  const elements = excalidrawAPI.getSceneElements();
+
+                  if (!elements.length) {
+                    return;
+                  }
+
+                  setHideAllForFadeDemo(true);
+
+                  const nextIndex =
+                    fadeDemoNextIndex >= elements.length
+                      ? 0
+                      : fadeDemoNextIndex;
+
+                  if (nextIndex === 0) {
+                    excalidrawAPI.clearElementOpacityOverrides();
+                  }
+
+                  console.info("Fading in element", {
+                    element: elements[nextIndex],
+                  });
+
+                  excalidrawAPI.fadeElement({
+                    id: elements[nextIndex].id,
+                    from: 0,
+                    to: 100,
+                    duration: 500,
+                  });
+
+                  setFadeDemoNextIndex(nextIndex + 1);
+                }}
+              >
+                Fade in next element
+              </button>
+              <button
+                onClick={() => {
+                  excalidrawAPI?.clearElementOpacityOverrides();
+                  setHideAllForFadeDemo(true);
+                  setFadeDemoNextIndex(0);
+                }}
+              >
+                Reset fade demo
+              </button>
+            </>
+          )}
           <button
             onClick={() => {
               const libraryItems: LibraryItems = [
diff --git a/examples/with-script-in-browser/initialData.tsx b/examples/with-script-in-browser/initialData.tsx
index 2b1a9d4820..9dc25c693b 100644
--- a/examples/with-script-in-browser/initialData.tsx
+++ b/examples/with-script-in-browser/initialData.tsx
@@ -2,6 +2,28 @@ import type { ExcalidrawElementSkeleton } from "@excalidraw/excalidraw/element/t
 import type { FileId } from "@excalidraw/excalidraw/element/types";
 
 const elements: ExcalidrawElementSkeleton[] = [
+  // {
+  //   type: "arrow",
+  //   x: 100,
+  //   y: 500,
+  // },
+  // {
+  //   type: "arrow",
+  //   x: 250,
+  //   y: 250,
+  //   label: {
+  //     text: "HELLO WORLD!!",
+  //   },
+  //   start: {
+  //     type: "rectangle",
+  //     // x: -100,
+  //   },
+  //   end: {
+  //     type: "ellipse",
+  //     // x: 300,
+  //   },
+  // },
+
   {
     type: "rectangle",
     x: 10,
@@ -22,14 +44,14 @@ const elements: ExcalidrawElementSkeleton[] = [
     },
     id: "2",
   },
-  {
-    type: "arrow",
-    x: 100,
-    y: 200,
-    label: { text: "HELLO WORLD!!" },
-    start: { type: "rectangle" },
-    end: { type: "ellipse" },
-  },
+  // {
+  //   type: "arrow",
+  //   x: 100,
+  //   y: 200,
+  //   label: { text: "HELLO WORLD!!" },
+  //   start: { type: "rectangle" },
+  //   end: { type: "ellipse" },
+  // },
   {
     type: "image",
     x: 606.1042326312408,
@@ -38,11 +60,11 @@ const elements: ExcalidrawElementSkeleton[] = [
     height: 230,
     fileId: "rocket" as FileId,
   },
-  {
-    type: "frame",
-    children: ["1", "2"],
-    name: "My frame",
-  },
+  // {
+  //   type: "frame",
+  //   children: ["1", "2"],
+  //   name: "My frame",
+  // },
 ];
 export default {
   elements,
diff --git a/packages/element/src/renderElement.ts b/packages/element/src/renderElement.ts
index 96bff999bc..6ce7538c33 100644
--- a/packages/element/src/renderElement.ts
+++ b/packages/element/src/renderElement.ts
@@ -1,6 +1,7 @@
 import rough from "roughjs/bin/rough";
 
 import {
+  clamp,
   type GlobalPoint,
   isRightAngleRads,
   lineSegment,
@@ -105,8 +106,36 @@ const getCanvasPadding = (element: ExcalidrawElement) => {
   }
 };
 
+export const resolveRenderOpacity = (
+  element: ExcalidrawElement,
+  renderConfig: Pick<
+    StaticCanvasRenderConfig,
+    "elementOpacityOverrides" | "resolveRenderOpacity"
+  >,
+) => {
+  const override = renderConfig.elementOpacityOverrides?.get(element.id);
+
+  if (override !== undefined) {
+    return clamp(override, 0, 100);
+  }
+
+  const resolvedOpacity = renderConfig.resolveRenderOpacity?.(
+    element as NonDeletedExcalidrawElement,
+  );
+
+  if (resolvedOpacity !== undefined) {
+    return clamp(resolvedOpacity, 0, 100);
+  }
+
+  return element.opacity;
+};
+
 export const getRenderOpacity = (
   element: ExcalidrawElement,
+  renderConfig: Pick<
+    StaticCanvasRenderConfig,
+    "elementOpacityOverrides" | "resolveRenderOpacity"
+  >,
   containingFrame: ExcalidrawFrameLikeElement | null,
   elementsPendingErasure: ElementsPendingErasure,
   pendingNodes: Readonly<PendingExcalidrawElements> | null,
@@ -115,7 +144,8 @@ export const getRenderOpacity = (
   // multiplying frame opacity with element opacity to combine them
   // (e.g. frame 50% and element 50% opacity should result in 25% opacity)
   let opacity =
-    (((containingFrame?.opacity ?? 100) * element.opacity) / 10000) *
+    (((containingFrame?.opacity ?? 100) * resolveRenderOpacity(element, renderConfig)) /
+      10000) *
     globalAlpha;
 
   // if pending erasure, multiply again to combine further
@@ -793,6 +823,7 @@ export const renderElement = (
 
   context.globalAlpha = getRenderOpacity(
     element,
+    renderConfig,
     getContainingFrame(element, elementsMap),
     renderConfig.elementsPendingErasure,
     renderConfig.pendingFlowchartNodes,
diff --git a/packages/excalidraw/components/App.tsx b/packages/excalidraw/components/App.tsx
index 2317ffc4f0..e236a22eec 100644
--- a/packages/excalidraw/components/App.tsx
+++ b/packages/excalidraw/components/App.tsx
@@ -207,10 +207,11 @@ import {
   getLineHeightInPx,
   getApproxMinLineWidth,
   getApproxMinLineHeight,
-  getMinTextElementWidth,
-  ShapeCache,
-  getRenderOpacity,
-  editGroupForSelectedElement,
+   getMinTextElementWidth,
+   ShapeCache,
+   getRenderOpacity,
+   resolveRenderOpacity,
+   editGroupForSelectedElement,
   getElementsInGroup,
   getSelectedGroupIdForElement,
   getSelectedGroupIds,
@@ -450,6 +451,7 @@ import { searchItemInFocusAtom } from "./SearchMenu";
 import { isSidebarDockedAtom } from "./Sidebar/Sidebar";
 import { StaticCanvas, InteractiveCanvas } from "./canvases";
 import NewElementCanvas from "./canvases/NewElementCanvas";
+import { AnimationController } from "../renderer/animation";
 import { isPointHittingLink } from "./hyperlink/helpers";
 import { MagicIcon, copyIcon, fullscreenIcon } from "./icons";
 import { AppStateObserver, type OnStateChange } from "./AppStateObserver";
@@ -740,6 +742,90 @@ class App extends React.Component<AppProps, AppState> {
   onRemoveEventListenersEmitter = new Emitter<[]>();
 
   api: ExcalidrawImperativeAPI;
+  private renderOpacityVersion = 0;
+  private elementOpacityOverrides = new Map<string, number>();
+  private elementFadeStates = new Map<
+    string,
+    {
+      from: number;
+      to: number;
+      duration: number;
+      delay: number;
+      elapsed: number;
+    }
+  >();
+
+  private getElementFadeAnimationKey = () => `${this.id}:fade-element`;
+
+  private bumpRenderOpacityVersion = () => {
+    this.renderOpacityVersion++;
+    this.setState({});
+  };
+
+  private getRenderOpacityConfig = () => ({
+    elementOpacityOverrides: this.elementOpacityOverrides,
+    resolveRenderOpacity: this.props.resolveRenderOpacity,
+  });
+
+  private getResolvedElementOpacity = (element: NonDeletedExcalidrawElement) => {
+    return resolveRenderOpacity(element, this.getRenderOpacityConfig());
+  };
+
+  private syncFadeElementAnimations = () => {
+    const animationKey = this.getElementFadeAnimationKey();
+
+    if (this.elementFadeStates.size === 0) {
+      AnimationController.cancel(animationKey);
+      return;
+    }
+
+    if (AnimationController.running(animationKey)) {
+      return;
+    }
+
+    AnimationController.start(animationKey, ({ deltaTime }) => {
+      let shouldRerender = false;
+
+      for (const [id, fade] of this.elementFadeStates) {
+        const element = this.scene.getNonDeletedElement(id);
+
+        if (!element) {
+          this.elementFadeStates.delete(id);
+          shouldRerender =
+            this.elementOpacityOverrides.delete(id) || shouldRerender;
+          continue;
+        }
+
+        fade.elapsed += deltaTime;
+
+        const nextOpacity =
+          fade.elapsed <= fade.delay
+            ? fade.from
+            : fade.duration === 0
+              ? fade.to
+              : fade.from +
+                (fade.to - fade.from) *
+                  Math.min((fade.elapsed - fade.delay) / fade.duration, 1);
+
+        const clampedOpacity = clamp(nextOpacity, 0, 100);
+
+        if (this.elementOpacityOverrides.get(id) !== clampedOpacity) {
+          this.elementOpacityOverrides.set(id, clampedOpacity);
+          shouldRerender = true;
+        }
+
+        if (fade.elapsed >= fade.delay + fade.duration) {
+          this.elementFadeStates.delete(id);
+        }
+      }
+
+      if (shouldRerender) {
+        this.bumpRenderOpacityVersion();
+      }
+
+      return this.elementFadeStates.size > 0 ? {} : undefined;
+    });
+  };
 
   private createExcalidrawAPI(): ExcalidrawImperativeAPI {
     const api: ExcalidrawImperativeAPI = {
@@ -757,6 +843,9 @@ class App extends React.Component<AppProps, AppState> {
         clear: this.resetHistory,
       },
       scrollToContent: this.scrollToContent,
+      fadeElement: this.fadeElement,
+      cancelFadeElement: this.cancelFadeElement,
+      clearElementOpacityOverrides: this.clearElementOpacityOverrides,
       getSceneElements: this.getSceneElements,
       getAppState: () => this.state,
       getFiles: () => this.files,
@@ -1762,6 +1851,7 @@ class App extends React.Component<AppProps, AppState> {
                 display: isVisible ? "block" : "none",
                 opacity: getRenderOpacity(
                   el,
+                  this.getRenderOpacityConfig(),
                   getContainingFrame(el, this.scene.getNonDeletedElementsMap()),
                   this.elementsPendingErasure,
                   null,
@@ -2351,6 +2441,8 @@ class App extends React.Component<AppProps, AppState> {
                               pendingFlowchartNodes:
                                 this.flowChartCreator.pendingNodes,
                               theme: this.state.theme,
+                              ...this.getRenderOpacityConfig(),
+                              renderOpacityVersion: this.renderOpacityVersion,
                             }}
                           />
                           {newElementCanvasElement && (
@@ -2373,6 +2465,9 @@ class App extends React.Component<AppProps, AppState> {
                                   this.elementsPendingErasure,
                                 pendingFlowchartNodes: null,
                                 theme: this.state.theme,
+                                ...this.getRenderOpacityConfig(),
+                                renderOpacityVersion:
+                                  this.renderOpacityVersion,
                               }}
                             />
                           )}
@@ -3206,6 +3301,7 @@ class App extends React.Component<AppProps, AppState> {
     this.editorLifecycleEvents.emit("editor:unmount");
     this.props.onUnmount?.();
     this.props.onExcalidrawAPI?.(null);
+    AnimationController.cancel(this.getElementFadeAnimationKey());
 
     (window as any).launchQueue?.setConsumer(() => {});
 
@@ -4618,6 +4714,77 @@ class App extends React.Component<AppProps, AppState> {
     },
   );
 
+  public fadeElement = ({
+    id,
+    from,
+    to = 100,
+    duration = 250,
+    delay = 0,
+  }: {
+    id: string;
+    from?: number;
+    to?: number;
+    duration?: number;
+    delay?: number;
+  }) => {
+    const element = this.scene.getNonDeletedElement(id);
+
+    if (!element) {
+      return;
+    }
+
+    const startOpacity = clamp(
+      from ?? this.getResolvedElementOpacity(element),
+      0,
+      100,
+    );
+    const targetOpacity = clamp(to, 0, 100);
+    const normalizedDuration = Math.max(duration, 0);
+    const normalizedDelay = Math.max(delay, 0);
+
+    this.elementOpacityOverrides.set(id, startOpacity);
+
+    if (normalizedDuration === 0 && normalizedDelay === 0) {
+      this.elementFadeStates.delete(id);
+      this.elementOpacityOverrides.set(id, targetOpacity);
+      this.bumpRenderOpacityVersion();
+      return;
+    }
+
+    this.elementFadeStates.set(id, {
+      from: startOpacity,
+      to: targetOpacity,
+      duration: normalizedDuration,
+      delay: normalizedDelay,
+      elapsed: 0,
+    });
+
+    this.bumpRenderOpacityVersion();
+    this.syncFadeElementAnimations();
+  };
+
+  public cancelFadeElement = (id: string) => {
+    if (!this.elementFadeStates.delete(id)) {
+      return;
+    }
+
+    this.syncFadeElementAnimations();
+  };
+
+  public clearElementOpacityOverrides = () => {
+    if (
+      this.elementOpacityOverrides.size === 0 &&
+      this.elementFadeStates.size === 0
+    ) {
+      return;
+    }
+
+    this.elementFadeStates.clear();
+    this.elementOpacityOverrides.clear();
+    this.syncFadeElementAnimations();
+    this.bumpRenderOpacityVersion();
+  };
+
   public applyDeltas = (
     deltas: StoreDelta[],
     options?: ApplyToOptions,
diff --git a/packages/excalidraw/index.tsx b/packages/excalidraw/index.tsx
index 64cedb3a8e..ab10f7288f 100644
--- a/packages/excalidraw/index.tsx
+++ b/packages/excalidraw/index.tsx
@@ -99,6 +99,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
     children,
     validateEmbeddable,
     renderEmbeddable,
+    resolveRenderOpacity,
     aiEnabled,
     showDeprecatedFonts,
     renderScrollbars,
@@ -217,6 +218,7 @@ const ExcalidrawBase = (props: ExcalidrawProps) => {
           onDuplicate={onDuplicate}
           validateEmbeddable={validateEmbeddable}
           renderEmbeddable={renderEmbeddable}
+          resolveRenderOpacity={resolveRenderOpacity}
           aiEnabled={aiEnabled !== false}
           showDeprecatedFonts={showDeprecatedFonts}
           renderScrollbars={renderScrollbars}
diff --git a/packages/excalidraw/renderer/staticScene.ts b/packages/excalidraw/renderer/staticScene.ts
index 48c72f8d37..4ad624bf13 100644
--- a/packages/excalidraw/renderer/staticScene.ts
+++ b/packages/excalidraw/renderer/staticScene.ts
@@ -14,11 +14,12 @@ import {
 } from "@excalidraw/element";
 import {
   elementOverlapsWithFrame,
+  getContainingFrame,
   getTargetFrame,
   shouldApplyFrameClip,
 } from "@excalidraw/element";
 
-import { renderElement } from "@excalidraw/element";
+import { getRenderOpacity, renderElement } from "@excalidraw/element";
 
 import { getElementAbsoluteCoords } from "@excalidraw/element";
 
@@ -170,6 +171,7 @@ const renderLinkIcon = (
   context: CanvasRenderingContext2D,
   appState: StaticCanvasAppState,
   elementsMap: ElementsMap,
+  renderConfig: StaticCanvasRenderConfig,
 ) => {
   if (element.link && !appState.selectedElementIds[element.id]) {
     const [x1, y1, x2, y2] = getElementAbsoluteCoords(element, elementsMap);
@@ -221,7 +223,13 @@ const renderLinkIcon = (
 
       linkCanvasCacheContext.restore();
     }
-    context.globalAlpha = element.opacity / 100;
+    context.globalAlpha = getRenderOpacity(
+      element,
+      renderConfig,
+      getContainingFrame(element, elementsMap),
+      renderConfig.elementsPendingErasure,
+      renderConfig.pendingFlowchartNodes,
+    );
     context.drawImage(linkCanvas, x - centerX, y - centerY, width, height);
     context.restore();
   }
@@ -370,7 +378,7 @@ const _renderStaticScene = ({
         context.restore();
 
         if (!isExporting) {
-          renderLinkIcon(element, context, appState, elementsMap);
+          renderLinkIcon(element, context, appState, elementsMap, renderConfig);
         }
       } catch (error: any) {
         console.error(
@@ -421,7 +429,7 @@ const _renderStaticScene = ({
             );
           }
           if (!isExporting) {
-            renderLinkIcon(element, context, appState, elementsMap);
+            renderLinkIcon(element, context, appState, elementsMap, renderConfig);
           }
         };
         // - when exporting the whole canvas, we DO NOT apply clipping
diff --git a/packages/excalidraw/scene/types.ts b/packages/excalidraw/scene/types.ts
index 59c421f8aa..4dbe05b6ab 100644
--- a/packages/excalidraw/scene/types.ts
+++ b/packages/excalidraw/scene/types.ts
@@ -12,6 +12,7 @@ import type {
   AppClassProperties,
   AppState,
   EmbedsValidationStatus,
+  RenderOpacityResolver,
   ElementsPendingErasure,
   InteractiveCanvasAppState,
   StaticCanvasAppState,
@@ -37,6 +38,9 @@ export type StaticCanvasRenderConfig = {
   elementsPendingErasure: ElementsPendingErasure;
   pendingFlowchartNodes: PendingExcalidrawElements | null;
   theme: AppState["theme"];
+  resolveRenderOpacity?: RenderOpacityResolver;
+  elementOpacityOverrides?: ReadonlyMap<ExcalidrawElement["id"], number>;
+  renderOpacityVersion?: number;
 };
 
 export type SVGRenderConfig = {
diff --git a/packages/excalidraw/types.ts b/packages/excalidraw/types.ts
index b40ec1b4e1..e90d40ba83 100644
--- a/packages/excalidraw/types.ts
+++ b/packages/excalidraw/types.ts
@@ -567,6 +567,10 @@ export type OnExportProgress = {
   progress?: number;
 };
 
+export type RenderOpacityResolver = (
+  element: NonDeletedExcalidrawElement,
+) => ExcalidrawElement["opacity"] | undefined;
+
 export interface ExcalidrawProps {
   onChange?: (
     elements: readonly OrderedExcalidrawElement[],
@@ -682,6 +686,7 @@ export interface ExcalidrawProps {
     element: NonDeleted<ExcalidrawEmbeddableElement>,
     appState: AppState,
   ) => JSX.Element | null;
+  resolveRenderOpacity?: RenderOpacityResolver;
   aiEnabled?: boolean;
   showDeprecatedFonts?: boolean;
   renderScrollbars?: boolean;
@@ -962,6 +967,11 @@ export interface ExcalidrawImperativeAPI {
   getFiles: () => InstanceType<typeof App>["files"];
   getName: InstanceType<typeof App>["getName"];
   scrollToContent: InstanceType<typeof App>["scrollToContent"];
+  fadeElement: InstanceType<typeof App>["fadeElement"];
+  cancelFadeElement: InstanceType<typeof App>["cancelFadeElement"];
+  clearElementOpacityOverrides: InstanceType<
+    typeof App
+  >["clearElementOpacityOverrides"];
   registerAction: (action: Action) => void;
   refresh: InstanceType<typeof App>["refresh"];
   setToast: InstanceType<typeof App>["setToast"];