react-useanimations 2.0.9 → 3.0.0-beta.1

package/README.md

@@ -4,37 +4,26 @@
 
 #### What is react-useanimations?
 
-React-useanimations is a collection of free animated open source icons for React.js.
+React-useanimations is the official React component for [useAnimations](https://useanimations.com), a free library of 85+ animated Lottie icons.
 
-#### Collection
-
-[https://react.useanimations.com](https://react.useanimations.com/) and play with examples or visit our [Storybook](https://useanimations.github.io/react-useanimations/)
+📖 **Documentation:** [useanimations.com/documentation](https://useanimations.com/documentation): React props and all import names, plus plain HTML/JS, Vue, iOS and Android guides.
 
 ![](useanimations-preview.gif)
 
 ### Installation
 
-Using Yarn:
-
 ```
-yarn add react-useanimations
+npm install react-useanimations
 ```
 
-or using NPM:
-
-```
-npm install -S react-useanimations
-```
+Requires React 16.8+ (tested with React 18 and 19). Works with StrictMode, Next.js (App Router) and other SSR frameworks.
 
 ### Usage
-If you still need to use v1, please refer to this README instead - [react-useanimations@v1](https://github.com/useAnimations/react-useanimations/blob/master/README_v1.md)
 
-Basic usage
 ```javascript
-import React from 'react';
 import UseAnimations from 'react-useanimations';
 // EVERY ANIMATION NEEDS TO BE IMPORTED FIRST -> YOUR BUNDLE WILL INCLUDE ONLY WHAT IT NEEDS
-import github from 'react-useanimations/lib/github'
+import github from 'react-useanimations/lib/github';
 
 const App = () => <UseAnimations animation={github} />;
 
@@ -44,67 +33,123 @@ export default App;
 Icons can be configured with inline props:
 
 ```javascript
-<UseAnimations animation={github} size={56} wrapperStyle={{ padding: 100 }} />
+<UseAnimations
+  animation={github}
+  size={56}
+  strokeColor="currentColor"
+  wrapperStyle={{ padding: 100 }}
+/>
 ```
 
 These props are available:
-| Prop           | Default      | Definition   |
-| :------------- | :----------: | -----------: |
-| animation   | / | animation file |
-|  size | `24`   | animation size    |
-|  strokeColor | `'inherit'`   | animation stroke color |
-|  fillColor   | `''`          | animation fill color
-|  wrapperStyle | `{}` | wrapper div styles |
-|  pathCss | `''` | css string for the animation path element |
-|  reverse | `false` | assing to `true` when eg. checkbox should be checked initally |
-|  autoplay | `false`* | false except in animations like loading etc. |
-|  loop | `false`* | false except in animations like loading etc. |
-|  options | `{}` | provide any other custom options which will override the default ones |
-|  speed | `1` | a number to determine the speed of lottie(1 is normal speed) |
-
-<br />
-Controlled checkbox example  
+
+| Prop         |  Default  |                                                                                                                   Definition |
+| :----------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------: |
+| animation    |     /     |                                                                     animation imported from `react-useanimations/lib/<name>` |
+| size         |   `24`    |                                                                                                         animation size in px |
+| strokeColor  |     /     |                                                                              stroke color of the icon, e.g. `'currentColor'` |
+| fillColor    |     /     |                                                                                                       fill color of the icon |
+| pathCss      |     /     |                                                                                  extra CSS declarations for the icon's paths |
+| wrapperStyle |   `{}`    |                                                                                                           wrapper div styles |
+| interaction  | per icon* |                                                    `'loop'`, `'click-toggle'`, `'click-replay'`, `'hover'` or `'hover-loop'` |
+| reverse      |  `false`  |                            for `click-toggle` icons: `true` shows the end state (e.g. a checked checkbox); can be controlled |
+| autoplay     | per icon* |                                                                                        `true` for looping icons like loaders |
+| loop         | per icon* |                                                                                        `true` for looping icons like loaders |
+| speed        |    `1`    |                                                                                           playback speed (1 is normal speed) |
+| options      |   `{}`    | any other [lottie-web options](https://github.com/airbnb/lottie-web#other-loading-options); applied when the animation loads |
+| render       |     /     |                                                                                  render prop for a custom wrapper, see below |
+
+\* Each icon has a default interaction matching [useanimations.com](https://useanimations.com):
+
+- `loop`: plays continuously (loaders, alerts).
+- `click-toggle`: toggles between two states on click (menu, checkbox, play/pause).
+- `click-replay`: replays from the start on every click.
+- `hover`: plays forward on mouse enter and backward on mouse leave.
+- `hover-loop`: loops while hovered (social icons).
+
+Any other prop (`className`, `aria-label`, `onClick`, `onMouseEnter`, …) is passed to the wrapper div. Your event handlers run before the animation's; call `event.preventDefault()` to skip the animation.
+
+#### Controlled toggle
 
 ```javascript
-export const RadioButton = () => {
-  // JUST EXAMPLE - THIS PART OF THE STATE WILL PROBABLY COME FROM A PARENT FORM COMPONENT
-  const [checked, setChecked] = useState(true);
+import { useState } from 'react';
+import UseAnimations from 'react-useanimations';
+import menu from 'react-useanimations/lib/menu';
+
+export const MenuButton = () => {
+  const [open, setOpen] = useState(false);
 
   return (
-    <div style={{ padding: '20px' }}>
-      <span>radioButton</span>
-      <UseAnimation
-        reverse={checked}
-        onClick={() => {
-          setChecked(!checked);
-        }}
-        size={40}
-        wrapperStyle={{ marginTop: '5px' }}
-        animation={radioButton}
-      />
-    </div>
+    <UseAnimations
+      animation={menu}
+      size={40}
+      reverse={open} // also animates when `open` changes elsewhere, e.g. the menu closes on Escape
+      onClick={() => setOpen(!open)}
+    />
   );
 };
 ```
 
-Animation wrapped in element (use render prop).
+#### Changing the interaction
+
 ```javascript
-export const WrapperElement = () => {
-  return (
-    <UseAnimation
-      animation={heart}
-      size={60}
-      onClick={() => {
-        // eslint-disable-next-line
-        console.log('additional onClick cb is working');
-      }}
-      render={(eventProps, animationProps) => (
-        <button style={{ padding: '20px' }} type="button" {...eventProps}>
-          <div {...animationProps} />
-        </button>
-      )}
-    />
-  );
-};
+<UseAnimations animation={download} interaction="hover" />
 ```
- Note that `eventProps` consists of `onClick`, `mouseOver` and other DOM events which you probably want to assign to your wrapping element (e.g. Button) and `animationProps` consist of an actual animation which you should spread inside a simple `<div>`   
+
+#### Wrapping the animation in another element
+
+```javascript
+import heart from 'react-useanimations/lib/heart';
+
+export const LikeButton = () => (
+  <UseAnimations
+    animation={heart}
+    size={60}
+    onClick={() => console.log('liked')}
+    render={(eventProps, animationProps) => (
+      <button type="button" aria-label="Like" {...eventProps}>
+        <div {...animationProps} />
+      </button>
+    )}
+  />
+);
+```
+
+`eventProps` holds the `onClick`, `onMouseEnter` and `onMouseLeave` handlers for your interactive element (e.g. a button) and `animationProps` holds the animation itself, which you spread inside a plain `<div>`.
+
+#### Next.js and other SSR frameworks
+
+The component is marked `'use client'` and loads lottie-web only in the browser, so it can be rendered from server components without `dynamic(..., { ssr: false })`.
+
+### Available animations
+
+<!-- icons:start -->
+
+`activity`, `airplay`, `alertCircle`, `alertOctagon`, `alertTriangle`, `archive`, `arrowDown`, `arrowDownCircle`, `arrowLeftCircle`, `arrowRightCircle`, `arrowUp`, `arrowUpCircle`, `behance`, `bookmark`, `calendar`, `checkBox`, `checkmark`, `chevronLeft`, `chevronRight`, `codepen`, `copy`, `download`, `dribbble`, `edit`, `error`, `explore`, `facebook`, `filter`, `folder`, `github`, `heart`, `help`, `home`, `infinity`, `info`, `instagram`, `linkedin`, `loading`, `loading2`, `loading3`, `loading4`, `lock`, `mail`, `maximizeMinimize`, `maximizeMinimize2`, `menu`, `menu2`, `menu3`, `menu4`, `microphone`, `microphone2`, `notification`, `notification2`, `notification3`, `notification4`, `playPause`, `playPauseCircle`, `plusToX`, `pocket`, `radioButton`, `refresh`, `scrollDown`, `searchToX`, `settings`, `settings2`, `share`, `skipBack`, `skipForward`, `star`, `thumbUp`, `toggle`, `trash`, `trash2`, `twitter`, `userMinus`, `userPlus`, `userX`, `video`, `video2`, `visibility`, `visibility2`, `visibility3`, `volume`, `youtube`, `youtube2`, `zoomIn`, `zoomOut`
+<!-- icons:end -->
+
+Import each one from `react-useanimations/lib/<name>`.
+
+### Upgrading from v2
+
+- Icon interactions now match useanimations.com (e.g. `zoomIn` plays on hover instead of looping, social icons loop while hovered). Pass `interaction` to keep a different behavior.
+- `reverse` is now fully controlled: changing it from `true` to `false` animates back.
+- `onMouseEnter` / `onMouseLeave` no longer replace the hover animation, and `style` is merged into the wrapper styles.
+- `loop={false}` and `autoplay={false}` now override the defaults of looping icons.
+- `options` is typed as lottie-web's `AnimationConfigWithData<'svg'>`.
+- The `react-useanimations/utils/*` paths were removed; import the types (`Animation`, `AnimationKey`, `Interaction`, `UseAnimationsProps`) from `react-useanimations`.
+
+### Development
+
+```
+npm install
+npm test            # vitest
+npm run lint
+npm run check-types
+npm run build       # builds dist/ (CJS + ESM + types)
+npm run sync-icons  # syncs src/lib with https://useanimations.com/icons.json
+```
+
+### License
+
+The animations are free for personal and commercial use under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/). Attribution with a link to [useanimations.com](https://useanimations.com) is required; redistributing or reselling the files themselves (e.g. in icon packs, templates or UI kits) is not allowed. See [LICENSE](LICENSE) and [Licencing & Terms](https://useanimations.com/licencing-and-terms).

package/index.d.mts

@@ -0,0 +1,144 @@
+import React from 'react';
+import { AnimationConfigWithData } from 'lottie-web';
+
+declare const interactions: {
+    readonly activity: "loop";
+    readonly airplay: "loop";
+    readonly alertCircle: "loop";
+    readonly alertOctagon: "loop";
+    readonly alertTriangle: "loop";
+    readonly archive: "hover";
+    readonly arrowDown: "loop";
+    readonly arrowDownCircle: "click-replay";
+    readonly arrowLeftCircle: "click-replay";
+    readonly arrowRightCircle: "click-replay";
+    readonly arrowUp: "loop";
+    readonly arrowUpCircle: "click-replay";
+    readonly behance: "hover-loop";
+    readonly bookmark: "click-toggle";
+    readonly calendar: "hover";
+    readonly checkBox: "click-toggle";
+    readonly checkmark: "loop";
+    readonly chevronLeft: "click-replay";
+    readonly chevronRight: "click-replay";
+    readonly codepen: "hover-loop";
+    readonly copy: "hover";
+    readonly download: "click-replay";
+    readonly dribbble: "hover-loop";
+    readonly edit: "hover";
+    readonly error: "loop";
+    readonly explore: "hover";
+    readonly facebook: "hover-loop";
+    readonly filter: "click-replay";
+    readonly folder: "hover";
+    readonly github: "hover-loop";
+    readonly heart: "click-toggle";
+    readonly help: "loop";
+    readonly home: "hover";
+    readonly infinity: "loop";
+    readonly info: "hover";
+    readonly instagram: "hover";
+    readonly linkedin: "hover-loop";
+    readonly loading: "loop";
+    readonly loading2: "loop";
+    readonly loading3: "loop";
+    readonly loading4: "loop";
+    readonly lock: "click-toggle";
+    readonly mail: "hover";
+    readonly maximizeMinimize: "click-toggle";
+    readonly maximizeMinimize2: "click-toggle";
+    readonly menu: "click-toggle";
+    readonly menu2: "click-toggle";
+    readonly menu3: "click-toggle";
+    readonly menu4: "click-toggle";
+    readonly microphone: "click-toggle";
+    readonly microphone2: "click-toggle";
+    readonly notification: "click-toggle";
+    readonly notification2: "click-toggle";
+    readonly notification3: "loop";
+    readonly notification4: "loop";
+    readonly playPause: "click-toggle";
+    readonly playPauseCircle: "click-toggle";
+    readonly plusToX: "click-toggle";
+    readonly pocket: "hover-loop";
+    readonly radioButton: "click-toggle";
+    readonly refresh: "click-replay";
+    readonly scrollDown: "loop";
+    readonly searchToX: "click-toggle";
+    readonly settings: "hover";
+    readonly settings2: "click-toggle";
+    readonly share: "hover";
+    readonly skipBack: "click-replay";
+    readonly skipForward: "click-replay";
+    readonly star: "click-toggle";
+    readonly thumbUp: "click-toggle";
+    readonly toggle: "click-toggle";
+    readonly trash: "hover";
+    readonly trash2: "hover";
+    readonly twitter: "hover-loop";
+    readonly userMinus: "hover";
+    readonly userPlus: "hover";
+    readonly userX: "hover";
+    readonly video: "click-toggle";
+    readonly video2: "click-toggle";
+    readonly visibility: "click-toggle";
+    readonly visibility2: "click-toggle";
+    readonly visibility3: "click-toggle";
+    readonly volume: "click-toggle";
+    readonly youtube: "hover";
+    readonly youtube2: "hover";
+    readonly zoomIn: "hover";
+    readonly zoomOut: "hover";
+};
+type AnimationKey = keyof typeof interactions;
+
+/**
+ * How an icon reacts to the user, matching the `interaction` field of the useAnimations catalog.
+ * - `loop`: plays continuously.
+ * - `click-toggle`: toggles between two states on click (forward, then backward).
+ * - `click-replay`: replays from the start on every click.
+ * - `hover`: plays forward on mouse enter and backward on mouse leave.
+ * - `hover-loop`: loops while hovered and stops on mouse leave.
+ */
+type Interaction = 'loop' | 'click-toggle' | 'click-replay' | 'hover' | 'hover-loop';
+type Animation = {
+    animationData: unknown;
+    animationKey: AnimationKey;
+};
+
+type MouseHandler = (event: React.MouseEvent<HTMLElement>) => void;
+type EventProps = {
+    onClick: MouseHandler;
+    onMouseEnter: MouseHandler;
+    onMouseLeave: MouseHandler;
+};
+type AnimationProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref: React.Ref<HTMLDivElement>;
+    style: React.CSSProperties;
+};
+type OwnProps = {
+    /** Animation imported from `react-useanimations/lib/<name>`. */
+    animation: Animation;
+    /** Overrides the icon's default interaction, e.g. `'hover'` for an icon that normally plays on click. */
+    interaction?: Interaction;
+    /** For `click-toggle` icons: `true` shows the end state (e.g. a checked checkbox). Can be controlled. */
+    reverse?: boolean;
+    strokeColor?: string;
+    fillColor?: string;
+    /** Extra CSS declarations applied to every path of the icon. */
+    pathCss?: string;
+    /** Extra lottie-web options, applied when the animation loads. */
+    options?: Partial<AnimationConfigWithData<'svg'>>;
+    size?: number;
+    loop?: boolean | number;
+    autoplay?: boolean;
+    speed?: number;
+    wrapperStyle?: React.CSSProperties;
+    /** Renders a custom wrapper: spread `eventProps` on the interactive element, `animationProps` on a div. */
+    render?: (eventProps: EventProps, animationProps: AnimationProps) => React.ReactElement;
+};
+type UseAnimationsProps = OwnProps & Omit<React.HTMLAttributes<HTMLDivElement>, keyof OwnProps>;
+
+declare const UseAnimations: (props: UseAnimationsProps) => React.ReactElement;
+
+export { type Animation, type AnimationKey, type AnimationProps, type EventProps, type Interaction, type UseAnimationsProps, UseAnimations as default };

package/index.d.ts

@@ -0,0 +1,144 @@
+import React from 'react';
+import { AnimationConfigWithData } from 'lottie-web';
+
+declare const interactions: {
+    readonly activity: "loop";
+    readonly airplay: "loop";
+    readonly alertCircle: "loop";
+    readonly alertOctagon: "loop";
+    readonly alertTriangle: "loop";
+    readonly archive: "hover";
+    readonly arrowDown: "loop";
+    readonly arrowDownCircle: "click-replay";
+    readonly arrowLeftCircle: "click-replay";
+    readonly arrowRightCircle: "click-replay";
+    readonly arrowUp: "loop";
+    readonly arrowUpCircle: "click-replay";
+    readonly behance: "hover-loop";
+    readonly bookmark: "click-toggle";
+    readonly calendar: "hover";
+    readonly checkBox: "click-toggle";
+    readonly checkmark: "loop";
+    readonly chevronLeft: "click-replay";
+    readonly chevronRight: "click-replay";
+    readonly codepen: "hover-loop";
+    readonly copy: "hover";
+    readonly download: "click-replay";
+    readonly dribbble: "hover-loop";
+    readonly edit: "hover";
+    readonly error: "loop";
+    readonly explore: "hover";
+    readonly facebook: "hover-loop";
+    readonly filter: "click-replay";
+    readonly folder: "hover";
+    readonly github: "hover-loop";
+    readonly heart: "click-toggle";
+    readonly help: "loop";
+    readonly home: "hover";
+    readonly infinity: "loop";
+    readonly info: "hover";
+    readonly instagram: "hover";
+    readonly linkedin: "hover-loop";
+    readonly loading: "loop";
+    readonly loading2: "loop";
+    readonly loading3: "loop";
+    readonly loading4: "loop";
+    readonly lock: "click-toggle";
+    readonly mail: "hover";
+    readonly maximizeMinimize: "click-toggle";
+    readonly maximizeMinimize2: "click-toggle";
+    readonly menu: "click-toggle";
+    readonly menu2: "click-toggle";
+    readonly menu3: "click-toggle";
+    readonly menu4: "click-toggle";
+    readonly microphone: "click-toggle";
+    readonly microphone2: "click-toggle";
+    readonly notification: "click-toggle";
+    readonly notification2: "click-toggle";
+    readonly notification3: "loop";
+    readonly notification4: "loop";
+    readonly playPause: "click-toggle";
+    readonly playPauseCircle: "click-toggle";
+    readonly plusToX: "click-toggle";
+    readonly pocket: "hover-loop";
+    readonly radioButton: "click-toggle";
+    readonly refresh: "click-replay";
+    readonly scrollDown: "loop";
+    readonly searchToX: "click-toggle";
+    readonly settings: "hover";
+    readonly settings2: "click-toggle";
+    readonly share: "hover";
+    readonly skipBack: "click-replay";
+    readonly skipForward: "click-replay";
+    readonly star: "click-toggle";
+    readonly thumbUp: "click-toggle";
+    readonly toggle: "click-toggle";
+    readonly trash: "hover";
+    readonly trash2: "hover";
+    readonly twitter: "hover-loop";
+    readonly userMinus: "hover";
+    readonly userPlus: "hover";
+    readonly userX: "hover";
+    readonly video: "click-toggle";
+    readonly video2: "click-toggle";
+    readonly visibility: "click-toggle";
+    readonly visibility2: "click-toggle";
+    readonly visibility3: "click-toggle";
+    readonly volume: "click-toggle";
+    readonly youtube: "hover";
+    readonly youtube2: "hover";
+    readonly zoomIn: "hover";
+    readonly zoomOut: "hover";
+};
+type AnimationKey = keyof typeof interactions;
+
+/**
+ * How an icon reacts to the user, matching the `interaction` field of the useAnimations catalog.
+ * - `loop`: plays continuously.
+ * - `click-toggle`: toggles between two states on click (forward, then backward).
+ * - `click-replay`: replays from the start on every click.
+ * - `hover`: plays forward on mouse enter and backward on mouse leave.
+ * - `hover-loop`: loops while hovered and stops on mouse leave.
+ */
+type Interaction = 'loop' | 'click-toggle' | 'click-replay' | 'hover' | 'hover-loop';
+type Animation = {
+    animationData: unknown;
+    animationKey: AnimationKey;
+};
+
+type MouseHandler = (event: React.MouseEvent<HTMLElement>) => void;
+type EventProps = {
+    onClick: MouseHandler;
+    onMouseEnter: MouseHandler;
+    onMouseLeave: MouseHandler;
+};
+type AnimationProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref: React.Ref<HTMLDivElement>;
+    style: React.CSSProperties;
+};
+type OwnProps = {
+    /** Animation imported from `react-useanimations/lib/<name>`. */
+    animation: Animation;
+    /** Overrides the icon's default interaction, e.g. `'hover'` for an icon that normally plays on click. */
+    interaction?: Interaction;
+    /** For `click-toggle` icons: `true` shows the end state (e.g. a checked checkbox). Can be controlled. */
+    reverse?: boolean;
+    strokeColor?: string;
+    fillColor?: string;
+    /** Extra CSS declarations applied to every path of the icon. */
+    pathCss?: string;
+    /** Extra lottie-web options, applied when the animation loads. */
+    options?: Partial<AnimationConfigWithData<'svg'>>;
+    size?: number;
+    loop?: boolean | number;
+    autoplay?: boolean;
+    speed?: number;
+    wrapperStyle?: React.CSSProperties;
+    /** Renders a custom wrapper: spread `eventProps` on the interactive element, `animationProps` on a div. */
+    render?: (eventProps: EventProps, animationProps: AnimationProps) => React.ReactElement;
+};
+type UseAnimationsProps = OwnProps & Omit<React.HTMLAttributes<HTMLDivElement>, keyof OwnProps>;
+
+declare const UseAnimations: (props: UseAnimationsProps) => React.ReactElement;
+
+export { type Animation, type AnimationKey, type AnimationProps, type EventProps, type Interaction, type UseAnimationsProps, UseAnimations as default };