feat: add shouldUpdateAnimation option

Author: wellyshen

README.md

@@ -34,7 +34,7 @@ Using [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_
 - 🔩 Supports custom `refs` for [some reasons](#use-your-own-ref).
 - 📜 Supports [TypeScript](https://www.typescriptlang.org) type definition.
 - 🗄️ Server-side rendering compatibility.
-- 🦔 Tiny size ([~ 4.8KB gzipped](https://bundlephobia.com/result?p=@wellyshen/use-web-animations)). No external dependencies, aside for the `react`.
+- 🦔 Tiny size ([~ 4.8KB gzipped](https://bundlephobia.com/result?p=@wellyshen/use-web-animations)).
 
 ## Requirement
 
@@ -129,6 +129,8 @@ const App = () => {
 };
 ```
 
+> 💡 By default, the hook will be updated when options changed (i.e. keyframes, animationOptions etc.). However, you can disable this behavior by setting the `shouldUpdateAnimation` option to `false`.
+
 ### Playback Control
 
 The shortcoming with existing technologies was the lack of playback control. The Web Animations API provides several useful methods for controlling playback: play, pause, reverse, cancel, finish, seek, control speed via the [methods](https://developer.mozilla.org/en-US/docs/Web/API/Animation#Methods) of the **Animation** interface. This hook exposes the animation instance for us to interact with animations, we can access it by the `getAnimation()` return value.
@@ -532,17 +534,18 @@ It's returned with the following properties.
 
 The `options` provides the following configurations and event callbacks for you.
 
-| Key                | Type             | Default | Description                                                                                                                                                                                                                                       |
-| ------------------ | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ref`              | object           |         | For [some reasons](#use-your-own-ref), you can pass in your own ref instead of using the built-in.                                                                                                                                                |
-| `id`               | string           | `""`    | Sets the ID of an animation, implemented based on the [Animation.id](https://developer.mozilla.org/en-US/docs/Web/API/Animation/id).                                                                                                              |
-| `playbackRate`     | number           | `1`     | Sets the playback rate of an animation, implemented based on the [Animation.playbackRate](https://developer.mozilla.org/en-US/docs/Web/API/Animation/playbackRate).                                                                               |
-| `autoPlay`         | boolean          | `true`  | Automatically starts the animation.                                                                                                                                                                                                               |
-| `keyframes`        | Array \| object  |         | An array of keyframe objects, or a keyframe object whose property are arrays of values to iterate over. See [basic usage](#basic-usage) for more details.                                                                                         |
-| `animationOptions` | number \| object |         | An **integer** representing the animation's duration (in milliseconds), or an **object** containing one or more timing properties. See [basic usage](#basic-usage) for more details.                                                              |
-| `onReady`          | function         |         | It's invoked when an animation is ready to play. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object.                            |
-| `onUpdate`         | function         |         | It's invoked when an animation enters the `running` state or changes state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |
-| `onFinish`         | function         |         | It's invoked when an animation enters the `finished` state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object.                 |
+| Key                     | Type             | Default | Description                                                                                                                                                                                                                                       |
+| ----------------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref`                   | object           |         | For [some reasons](#use-your-own-ref), you can pass in your own ref instead of using the built-in.                                                                                                                                                |
+| `id`                    | string           | `""`    | Sets the ID of an animation, implemented based on the [Animation.id](https://developer.mozilla.org/en-US/docs/Web/API/Animation/id).                                                                                                              |
+| `playbackRate`          | number           | `1`     | Sets the playback rate of an animation, implemented based on the [Animation.playbackRate](https://developer.mozilla.org/en-US/docs/Web/API/Animation/playbackRate).                                                                               |
+| `autoPlay`              | boolean          | `true`  | Automatically starts the animation.                                                                                                                                                                                                               |
+| `keyframes`             | Array \| object  |         | An array of keyframe objects, or a keyframe object whose property are arrays of values to iterate over. See [basic usage](#basic-usage) for more details.                                                                                         |
+| `animationOptions`      | number \| object |         | An **integer** representing the animation's duration (in milliseconds), or an **object** containing one or more timing properties. See [basic usage](#basic-usage) for more details.                                                              |
+| `shouldUpdateAnimation` | boolean          | `true`  | By default, the hook will be updated when options changed (i.e. keyframes, animationOptions etc.). However, you can disable this behavior by setting this option to `false`.                                                                      |
+| `onReady`               | function         |         | It's invoked when an animation is ready to play. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object.                            |
+| `onUpdate`              | function         |         | It's invoked when an animation enters the `running` state or changes state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |
+| `onFinish`              | function         |         | It's invoked when an animation enters the `finished` state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object.                 |
 
 ## Use Polyfill
 

src/__tests__/useWebAnimations.ts

@@ -22,10 +22,19 @@ describe("useWebAnimations", () => {
     ref = target,
     keyframes = mockKeyframes,
     animationOptions = mockTiming,
+    shouldUpdateAnimation = true,
     ...rest
   }: Partial<Options<HTMLDivElement>> = {}) =>
-    renderHook(() =>
-      useWebAnimations({ ref, keyframes, animationOptions, ...rest })
+    renderHook(
+      (config) => useWebAnimations({ ...config, shouldUpdateAnimation }),
+      {
+        initialProps: {
+          ref,
+          keyframes,
+          animationOptions,
+          ...rest,
+        },
+      }
     );
 
   const e = { playState: "pause" };
@@ -44,6 +53,32 @@ describe("useWebAnimations", () => {
     el.animate = jest.fn(() => animation);
   });
 
+  it("should update animation", () => {
+    const { rerender } = renderHelper();
+    expect(el.animate).toHaveBeenCalledWith(mockKeyframes, 3000);
+    const elm = document.createElement("div");
+    // @ts-expect-error
+    elm.animate = jest.fn(() => animation);
+    const keyframes = { transform: ["translateX(100px)"] };
+    const animationOptions = 5000;
+    rerender({ ref: { current: elm }, keyframes, animationOptions });
+    expect(elm.animate).toHaveBeenCalledWith(keyframes, animationOptions);
+  });
+
+  it("should not update animation", () => {
+    const { rerender } = renderHelper({ shouldUpdateAnimation: false });
+    expect(el.animate).toHaveBeenCalledWith(mockKeyframes, 3000);
+    const elm = document.createElement("div");
+    // @ts-expect-error
+    elm.animate = jest.fn(() => animation);
+    rerender({
+      ref: { current: elm },
+      keyframes: { transform: ["translateX(100px)"] },
+      animationOptions: 5000,
+    });
+    expect(elm.animate).not.toHaveBeenCalled();
+  });
+
   it("should cancel animation", async () => {
     const { unmount } = renderHelper();
     unmount();

src/use-web-animations.d.ts

@@ -12,6 +12,7 @@ declare module "@wellyshen/use-web-animations" {
     animationOptions:
       | number
       | (KeyframeAnimationOptions & { pseudoElement?: string });
+    shouldUpdateAnimation: boolean;
   }>;
 
   export interface Animate {

src/useWebAnimations.ts

@@ -17,6 +17,7 @@ type AnimConf = Partial<{
   animationOptions:
     | number
     | (KeyframeAnimationOptions & { pseudoElement?: string });
+  shouldUpdateAnimation: boolean;
 }>;
 interface Animate {
   (args: AnimConf & { keyframes: Keyframes }): void;
@@ -49,6 +50,7 @@ const useWebAnimations = <T extends HTMLElement>({
   autoPlay,
   keyframes,
   animationOptions,
+  shouldUpdateAnimation = true,
   onReady,
   onUpdate,
   onFinish,
@@ -121,9 +123,14 @@ const useWebAnimations = <T extends HTMLElement>({
     [onFinishRef, onReadyRef, ref]
   );
 
-  useDeepCompareEffect(() => {
-    animate({ id, playbackRate, autoPlay, keyframes, animationOptions });
-  }, [id, playbackRate, autoPlay, keyframes, animationOptions, animate]);
+  useDeepCompareEffect(
+    () => {
+      animate({ id, playbackRate, autoPlay, keyframes, animationOptions });
+    },
+    shouldUpdateAnimation
+      ? [id, playbackRate, autoPlay, keyframes, animationOptions, animate]
+      : [{}]
+  );
 
   useEffect(() => {
     let rafId: number;