react-useanimations 2.10.0 → 3.0.0-beta.1

package/LICENSE

@@ -0,0 +1,30 @@
+RIGHTS
+
+All the free files available in useAnimations are distributed
+under Creative Commons (CC) Attribution (BY) unless stated otherwise.
+Our resources (animations) can be used for personal and commercial usage
+within Web and Mobile Applications.
+
+You may modify the resources according to your requirements and use them
+in any or all of your personal or commercial projects. For example,
+you may include this resource on a website or mobile application
+you will be designing for a client.
+
+You are required to attribute or link to useanimations.com in any of projects.
+useAnimations (useanimations.com) will not be responsible for any outcome
+that may occur during the use of our resources.
+
+Files from useAnimations can be shared as long as the useAnimations
+are credited appropriately. 
+
+
+PROHIBITIONS
+
+You do not have the rights to redistribute, resell, lease, license,
+sub-license or offer the file downloaded to any third party.
+For any resalable web applications, software programs, web templates,
+app templates, merchandise etc. you should not include our graphics resources.
+This will be considered as a redistribution of our resources
+which is forbidden by us.
+
+More about Creative Commons (CC) Attribution (BY) - https://creativecommons.org/licenses/by/4.0/

package/README.md

@@ -0,0 +1,155 @@
+## React UseAnimations Icons
+
+[![npm version](https://img.shields.io/npm/v/react-useanimations.svg?style=flat-square)](https://www.npmjs.com/package/react-useanimations) [![npm downloads](https://img.shields.io/npm/dm/react-useanimations.svg?style=flat-square)](https://www.npmjs.com/package/react-useanimations)
+
+#### What is react-useanimations?
+
+React-useanimations is the official React component for [useAnimations](https://useanimations.com), a free library of 85+ animated Lottie icons.
+
+📖 **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
+
+```
+npm install react-useanimations
+```
+
+Requires React 16.8+ (tested with React 18 and 19). Works with StrictMode, Next.js (App Router) and other SSR frameworks.
+
+### Usage
+
+```javascript
+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';
+
+const App = () => <UseAnimations animation={github} />;
+
+export default App;
+```
+
+Icons can be configured with inline props:
+
+```javascript
+<UseAnimations
+  animation={github}
+  size={56}
+  strokeColor="currentColor"
+  wrapperStyle={{ padding: 100 }}
+/>
+```
+
+These props are available:
+
+| 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
+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 (
+    <UseAnimations
+      animation={menu}
+      size={40}
+      reverse={open} // also animates when `open` changes elsewhere, e.g. the menu closes on Escape
+      onClick={() => setOpen(!open)}
+    />
+  );
+};
+```
+
+#### Changing the interaction
+
+```javascript
+<UseAnimations animation={download} interaction="hover" />
+```
+
+#### 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

@@ -1,19 +1,144 @@
-import React, { ReactElement } from 'react';
-import type { AnimationConfig } from 'lottie-web';
-import type { Animation } from './utils';
-declare type Props = {
+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;
-    options?: Partial<AnimationConfig>;
+    /** Extra lottie-web options, applied when the animation loads. */
+    options?: Partial<AnimationConfigWithData<'svg'>>;
     size?: number;
-    loop?: AnimationConfig['loop'];
-    autoplay?: AnimationConfig['autoplay'];
+    loop?: boolean | number;
+    autoplay?: boolean;
     speed?: number;
     wrapperStyle?: React.CSSProperties;
-    render?: (eventProps: any, animationProps: any) => ReactElement;
-} & React.HTMLProps<HTMLDivElement>;
-declare const UseAnimations: React.FC<Props>;
-export default UseAnimations;
+    /** 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 };