\n\n### β¨ Six Animation Types Available\n\n- **π΅ Circle**: Smooth expanding circle transition\n- **π Blur Circle**: Circle with elegant blur effect on the edges\n- **π± QR Scan**: Scanning line sweeps left to right (like QR code reader)\n- **π· Polygon**: Diagonal wipe that sweeps across the screen\n- **π Polygon Gradient**: Diagonal wipe with a soft gradient edge\n- **π¬ Custom GIF**: Reveal the new theme through any GIF mask of your choice\n\n## π Notes\n\n- The hook is only available in the browser environment. So if you use NextJS App router or any other framework that uses Server Components, you should use this hook in a Client Component by adding the directive [`use client`](https://react.dev/reference/react/use-client)\n- Currently works only if the project is using TailwindCSS\n- Ensure your project has the necessary TailwindCSS configuration for dark mode\n\n## π Features\n\n- **π¨ Multiple Animation Types**: Circle, Blur Circle, QR Scan, Polygon, Polygon Gradient, and Custom GIF animations\n- **β‘ High Performance**: Optimized for high-resolution displays with smooth 60fps animations\n- **π― View Transition API**: Leverages modern browser APIs for seamless transitions\n- **π± Responsive Design**: Works perfectly across all device sizes and screen resolutions\n- **βΏ Accessibility First**: Respects `prefers-reduced-motion` and provides fallback experiences\n- **π§ TypeScript Support**: Full TypeScript support for enhanced development experience\n- **πΎ State Persistence**: Uses `localStorage` to persist theme state across sessions\n- **ποΈ Highly Customizable**: Configure duration, easing, blur amount, and more\n- **πͺ React Hooks**: Clean, modern React Hooks API\n\n## π¦ Installation\n\nInstall the package using npm or YARN:\n\n```bash\nnpm install react-theme-switch-animation\n```\n\nor\n\n```bash\nyarn add react-theme-switch-animation\n```\n\n## π Usage\n\nHereβs how to use the `useModeAnimation` hook in your React component:\n\n```jsx\n'use client'\n\nimport React from 'react'\nimport { useModeAnimation } from 'react-theme-switch-animation'\n\nconst MyComponent = () => {\n const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation()\n\n return (\n \n )\n}\n\nexport default MyComponent\n```\n\n## π API\n\n`useModeAnimation` accepts an optional `props` object with the following properties:\n\n| Property | Type | Default | Description |\n| ------------------ | ------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| `duration` | number | `750` | Duration of the animation in milliseconds (defaults to `1500` for `POLYGON_GRADIENT` and `2000` for `GIF`). |\n| `easing` | string | `\"ease-in-out\"` | CSS easing for the animation (defaults to an expo curve for `POLYGON`, `POLYGON_GRADIENT`, and `GIF`). |\n| `pseudoElement` | string | `\"::view-transition-new(root)\"` | Pseudo-element used for the animation. |\n| `globalClassName` | string | `\"dark\"` | Class name to apply to the root element. |\n| `animationType` | ThemeAnimationType | `ThemeAnimationType.CIRCLE` | Type of animation effect (`CIRCLE`, `BLUR_CIRCLE`, `QR_SCAN`, `POLYGON`, `POLYGON_GRADIENT`, `GIF`) |\n| `direction` | ThemeAnimationDirection | `ThemeAnimationDirection.LTR` | Sweep direction for the `QR_SCAN` animation (`LTR`, `RTL`, `TTB`, `BTT`). |\n| `blurAmount` | number | `2` | Blur intensity for blur circle animation. |\n| `gifUrl` | string | `undefined` | URL of the GIF used as the reveal mask (required for the `GIF` animation type). |\n| `styleId` | string | `\"theme-switch-style\"` | ID for the injected style element (blur circle, polygon gradient, and gif animations). |\n| `isDarkMode` | boolean | `false` | Initial dark mode state. |\n| `onDarkModeChange` | (isDark: boolean) => void | `undefined` | Callback function to handle dark mode change. |\n\n### Animation Types\n\nThe hook supports six types of animations:\n\n- `ThemeAnimationType.CIRCLE`: A clean circle expansion animation (default)\n- `ThemeAnimationType.BLUR_CIRCLE`: A circle expansion with blur effect on the edges\n- `ThemeAnimationType.QR_SCAN`: A scanning line that sweeps across the screen β configurable direction via the `direction` prop (left to right by default)\n- `ThemeAnimationType.POLYGON`: A diagonal wipe β toward dark it sweeps from the top-left corner, back to light from the bottom-right\n- `ThemeAnimationType.POLYGON_GRADIENT`: A diagonal wipe with a soft gradient edge expanding from the top-left corner\n- `ThemeAnimationType.GIF`: Reveals the new theme through a custom GIF mask that scales up to fill the screen (requires `gifUrl`)\n\n### Examples for Each Animation Type\n\n#### Circle Animation (Default)\n\n```jsx\n'use client'\n\nimport React from 'react'\nimport { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'\n\nconst CircleAnimation = () => {\n const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({\n animationType: ThemeAnimationType.CIRCLE,\n })\n\n return (\n \n )\n}\n```\n\n#### Blur Circle Animation\n\n```jsx\n'use client'\n\nimport React from 'react'\nimport { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'\n\nconst BlurCircleAnimation = () => {\n const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({\n animationType: ThemeAnimationType.BLUR_CIRCLE,\n blurAmount: 4, // Optional: adjust blur intensity\n duration: 1000, // Optional: adjust animation duration\n })\n\n return (\n \n )\n}\n```\n\n#### QR Scan Animation\n\n```jsx\n'use client'\n\nimport React from 'react'\nimport { ThemeAnimationDirection, ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'\n\nconst QRScanAnimation = () => {\n const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({\n animationType: ThemeAnimationType.QR_SCAN,\n direction: ThemeAnimationDirection.LTR, // Optional: LTR (default), RTL, TTB, or BTT\n duration: 500, // Faster scan animation\n })\n\n return (\n \n )\n}\n```\n\nThe scan direction can be customized with `ThemeAnimationDirection`:\n\n- `ThemeAnimationDirection.LTR`: left to right (default)\n- `ThemeAnimationDirection.RTL`: right to left\n- `ThemeAnimationDirection.TTB`: top to bottom\n- `ThemeAnimationDirection.BTT`: bottom to top\n\nString literals (`'ltr'`, `'rtl'`, `'ttb'`, `'btt'`) are also accepted.\n\n#### Polygon Animation\n\n```jsx\n'use client'\n\nimport React from 'react'\nimport { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'\n\nconst PolygonAnimation = () => {\n const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({\n animationType: ThemeAnimationType.POLYGON,\n })\n\n return (\n \n )\n}\n```\n\n#### Polygon Gradient Animation\n\n```jsx\n'use client'\n\nimport React from 'react'\nimport { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'\n\nconst PolygonGradientAnimation = () => {\n const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({\n animationType: ThemeAnimationType.POLYGON_GRADIENT,\n duration: 1500, // Optional: defaults to 1500ms for this animation\n })\n\n return (\n \n )\n}\n```\n\n#### Custom GIF Animation\n\n```jsx\n'use client'\n\nimport React from 'react'\nimport { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'\n\nconst GifAnimation = () => {\n const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({\n animationType: ThemeAnimationType.GIF,\n gifUrl: 'https://media.tenor.com/cyORI7kwShQAAAAi/shigure-ui-dance.gif', // Any GIF URL\n duration: 2000, // Optional: defaults to 2000ms for this animation\n })\n\n return (\n \n )\n}\n```\n\n> **Tip:** GIFs with transparent backgrounds work best as masks β the theme is revealed through the opaque parts of the GIF. If `gifUrl` is omitted, the hook falls back to the circle animation.\n\nReturns an object containing:\n\n- `ref`: React ref for attaching to the component that will trigger the dark mode toggle.\n- `toggleSwitchTheme`: Function to toggle dark mode.\n- `isDarkMode`: Current state of dark mode (`true` for dark, `false` for light).\n\n## β‘ Performance & Optimization\n\nThis library is built with performance in mind:\n\n- **High-Resolution Display Support**: Automatically detects and optimizes for displays β₯3000px width/height\n- **Adaptive Animation Duration**: Reduces duration by 20% on high-res displays for smoother experience\n- **GPU Acceleration**: Uses hardware-accelerated CSS properties (`transform`, `clip-path`, `mask`)\n- **Memory Efficient**: Automatic cleanup of style elements and event listeners\n- **Accessibility**: Respects `prefers-reduced-motion` for users who prefer minimal animations\n\n## π Browser Support\n\n- **Modern Browsers**: Chrome 111+, Firefox 103+, Safari 16.4+\n- **View Transition API**: Falls back gracefully on unsupported browsers\n- **Progressive Enhancement**: Basic theme switching works everywhere, animations enhance the experience\n\n## π Requirements\n\n- React 16.8 or later (for Hooks support)\n- TypeScript for compiling the package during installation\n- TailwindCSS for styling (ensure dark mode is configured)\n\n## π Acknowledgements\n\nThe polygon, polygon gradient, and GIF animations are inspired by [rudrodip/theme-toggle-effect](https://github.com/rudrodip/theme-toggle-effect).\n\n## π€ Contributing\n\nContributions are welcome! Please open an issue or submit a pull request with your suggested changes.\n\n## π License\n\nMIT\n","readmeFilename":"README.md"}