React Theme Switch Animation Hook

Beautiful, smooth animations for theme switching in React applications. Built with TypeScript and powered by the View Transition API.

🚀 Live Demo |
📦 npm Package |
💼 Hire me

🎥 Demo

$3

- 🔵 Circle: Smooth expanding circle transition
- 🌀 Blur Circle: Circle with elegant blur effect on the edges
- 📱 QR Scan: Scanning line sweeps left to right (like QR code reader)

📝 Notes

- 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
- Currently works only if the project is using TailwindCSS
- Ensure your project has the necessary TailwindCSS configuration for dark mode

🚀 Features

- 🎨 Multiple Animation Types: Circle, Blur Circle, and QR Scan animations
- ⚡ High Performance: Optimized for high-resolution displays with smooth 60fps animations
- 🎯 View Transition API: Leverages modern browser APIs for seamless transitions
- 📱 Responsive Design: Works perfectly across all device sizes and screen resolutions
- ♿ Accessibility First: Respects prefers-reduced-motion and provides fallback experiences
- 🔧 TypeScript Support: Full TypeScript support for enhanced development experience
- 💾 State Persistence: Uses localStorage to persist theme state across sessions
- 🎛️ Highly Customizable: Configure duration, easing, blur amount, and more
- 🪝 React Hooks: Clean, modern React Hooks API

📦 Installation

Install the package using npm or YARN:

``bash
npm install react-theme-switch-animation
`

or

`bash
yarn add react-theme-switch-animation
`

📚 Usage

Here’s how to use the useModeAnimation hook in your React component:

`jsx
'use client'

import React from 'react'
import { useModeAnimation } from 'react-theme-switch-animation'

const MyComponent = () => {
const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation()

return (

Toggle Dark Mode (Currently {isDarkMode ? 'Dark' : 'Light'} Mode)

)
}

export default MyComponent
`

📚 API

useModeAnimation accepts an optional props object with the following properties:

| Property | Type | Default | Description |
| ------------------ | ------------------------- | ------------------------------- | ------------------------------------------------------------- |
| duration | number | 750 | Duration of the animation in milliseconds. |
| easing | string | "ease-in-out" | CSS easing type for the animation. |
| pseudoElement | string | "::view-transition-new(root)" | Pseudo-element used for the animation. |
| globalClassName | string | "dark" | Class name to apply to the root element. |
| animationType | ThemeAnimationType | ThemeAnimationType.CIRCLE | Type of animation effect (CIRCLE, BLUR_CIRCLE, QR_SCAN) |
| blurAmount | number | 2 | Blur intensity for blur circle animation. |
| styleId | string | "theme-switch-style" | ID for the style element (blur circle animation). |
| isDarkMode | boolean | false | Initial dark mode state. |
| onDarkModeChange | (isDark: boolean) => void | undefined | Callback function to handle dark mode change. |

$3

The hook supports three types of animations:

- ThemeAnimationType.CIRCLE: A clean circle expansion animation (default)
- ThemeAnimationType.BLUR_CIRCLE: A circle expansion with blur effect on the edges
- ThemeAnimationType.QR_SCAN: A scanning line that sweeps from left to right

$3

#### Circle Animation (Default)

`jsx
'use client'

import React from 'react'
import { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'

const CircleAnimation = () => {
const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({
animationType: ThemeAnimationType.CIRCLE,
})

return (

{isDarkMode ? '🌙' : '☀️'} Toggle Theme

)
}
`

#### Blur Circle Animation

`jsx
'use client'

import React from 'react'
import { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'

const BlurCircleAnimation = () => {
const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({
animationType: ThemeAnimationType.BLUR_CIRCLE,
blurAmount: 4, // Optional: adjust blur intensity
duration: 1000, // Optional: adjust animation duration
})

return (

{isDarkMode ? '🌙' : '☀️'} Toggle Theme (Blur)

)
}
`

#### QR Scan Animation

`jsx
'use client'

import React from 'react'
import { ThemeAnimationType, useModeAnimation } from 'react-theme-switch-animation'

const QRScanAnimation = () => {
const { ref, toggleSwitchTheme, isDarkMode } = useModeAnimation({
animationType: ThemeAnimationType.QR_SCAN,
duration: 500, // Faster scan animation
})

return (

{isDarkMode ? '🌙' : '☀️'} Toggle Theme (QR Scan)

)
}
`

Returns an object containing:

- ref: React ref for attaching to the component that will trigger the dark mode toggle.
- toggleSwitchTheme: Function to toggle dark mode.
- isDarkMode: Current state of dark mode (true for dark, false for light).

⚡ Performance & Optimization

This library is built with performance in mind:

- High-Resolution Display Support: Automatically detects and optimizes for displays ≥3000px width/height
- Adaptive Animation Duration: Reduces duration by 20% on high-res displays for smoother experience
- GPU Acceleration: Uses hardware-accelerated CSS properties (transform, clip-path, mask)
- Memory Efficient: Automatic cleanup of style elements and event listeners
- Accessibility: Respects prefers-reduced-motion` for users who prefer minimal animations

🌐 Browser Support

- Modern Browsers: Chrome 111+, Firefox 103+, Safari 16.4+
- View Transition API: Falls back gracefully on unsupported browsers
- Progressive Enhancement: Basic theme switching works everywhere, animations enhance the experience

📝 Requirements

- React 16.8 or later (for Hooks support)
- TypeScript for compiling the package during installation
- TailwindCSS for styling (ensure dark mode is configured)

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request with your suggested changes.

📜 License

MIT