React Theme Toggle Button

React dark mode toggle with animated sun/moon icons and View Transitions API. Smooth theme switching with multiple animation effects, TypeScript, and shadcn/ui.

React

View Transitions API

Next Themes

Building theme switching interfaces?

Join our Discord community for help from other developers.

Dark mode toggles are everywhere—navigation bars, settings panels, user dashboards. But most just swap colors instantly. Jarring. Disconnected. No visual continuity. Meanwhile, users expect smooth transitions that feel intentional and polished. This React component gives you cinematic theme switching powered by the View Transitions API, creating seamless visual bridges between light and dark modes that delight users.

Loading component...

'use client'import React, { useCallback, useEffect, useState } from "react"import { useTheme } from 'next-themes'import { useSettings } from '@/hooks/useSettings'import type { Mode } from '@/contexts/settingsContext'import { ThemeToggleButton, useThemeTransition } from "@/components/ui/shadcn-io/theme-toggle-button"const ThemeToggleVariantsDemo = () => {  const { setTheme } = useTheme()  const { settings, updateSettings } = useSettings()  const { startTransition } = useThemeTransition()  const [mounted, setMounted] = useState(false)  useEffect(() => {    setMounted(true)  }, [])  const handleThemeToggle = useCallback(() => {    const newMode: Mode = settings.mode === 'dark' ? 'light' : 'dark'        startTransition(() => {      const updatedSettings = {        ...settings,        mode: newMode,        theme: {          ...settings.theme,          styles: {            light: settings.theme.styles?.light || {},            dark: settings.theme.styles?.dark || {}          }        }      }      updateSettings(updatedSettings)      setTheme(newMode)    })  }, [settings, updateSettings, setTheme, startTransition])  const currentTheme = settings.mode === 'system' ? 'light' : settings.mode as 'light' | 'dark'  if (!mounted) {    return null  }  return (    <div className="flex items-center justify-center gap-8 p-8">      {/* Circle animation */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="circle"          start="center"        />        <div className="text-center">          <span className="text-xs font-medium">Circle</span>          <p className="text-xs text-muted-foreground">Expanding circle</p>        </div>      </div>      {/* Circle blur animation */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="circle-blur"          start="top-right"        />        <div className="text-center">          <span className="text-xs font-medium">Circle Blur</span>          <p className="text-xs text-muted-foreground">Soft-edge circle</p>        </div>      </div>      {/* Polygon animation */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="polygon"        />        <div className="text-center">          <span className="text-xs font-medium">Polygon</span>          <p className="text-xs text-muted-foreground">Diagonal wipe</p>        </div>      </div>      {/* GIF animation */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="gif"          url="https://media.giphy.com/media/KBbr4hHl9DSahKvInO/giphy.gif?cid=790b76112m5eeeydoe7et0cr3j3ekb1erunxozyshuhxx2vl&ep=v1_stickers_search&rid=giphy.gif&ct=s"        />        <div className="text-center">          <span className="text-xs font-medium">GIF Mask</span>          <p className="text-xs text-muted-foreground">Custom animation</p>        </div>      </div>    </div>  )}export default ThemeToggleVariantsDemo

'use client';import { Moon, Sun } from 'lucide-react';import { useCallback } from 'react';import { Button } from '@/components/ui/button';import { cn } from '@/lib/utils';type AnimationVariant =   | 'circle'   | 'circle-blur'   | 'gif'  | 'polygon';type StartPosition =   | 'center'   | 'top-left'   | 'top-right'   | 'bottom-left'   | 'bottom-right';export interface ThemeToggleButtonProps {  theme?: 'light' | 'dark';  showLabel?: boolean;  variant?: AnimationVariant;  start?: StartPosition;  url?: string; // For gif variant  className?: string;  onClick?: () => void;}export const ThemeToggleButton = ({  theme = 'light',  showLabel = false,  variant = 'circle',  start = 'center',  url,  className,  onClick,}: ThemeToggleButtonProps) => {    const handleClick = useCallback(() => {    // Inject animation styles for this specific transition    const styleId = `theme-transition-${Date.now()}`;    const style = document.createElement('style');    style.id = styleId;        // Generate animation CSS based on variant    let css = '';    const positions = {      center: 'center',      'top-left': 'top left',      'top-right': 'top right',      'bottom-left': 'bottom left',      'bottom-right': 'bottom right',    };        if (variant === 'circle') {      const cx = start === 'center' ? '50' : start.includes('left') ? '0' : '100';      const cy = start === 'center' ? '50' : start.includes('top') ? '0' : '100';      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {             animation: none;          }          ::view-transition-new(root) {            animation: circle-expand 0.4s ease-out;            transform-origin: ${positions[start]};          }          @keyframes circle-expand {            from {              clip-path: circle(0% at ${cx}% ${cy}%);            }            to {              clip-path: circle(150% at ${cx}% ${cy}%);            }          }        }      `;    } else if (variant === 'circle-blur') {      const cx = start === 'center' ? '50' : start.includes('left') ? '0' : '100';      const cy = start === 'center' ? '50' : start.includes('top') ? '0' : '100';      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {             animation: none;          }          ::view-transition-new(root) {            animation: circle-blur-expand 0.5s ease-out;            transform-origin: ${positions[start]};            filter: blur(0);          }          @keyframes circle-blur-expand {            from {              clip-path: circle(0% at ${cx}% ${cy}%);              filter: blur(4px);            }            to {              clip-path: circle(150% at ${cx}% ${cy}%);              filter: blur(0);            }          }        }      `;    } else if (variant === 'gif' && url) {      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {            animation: fade-out 0.4s ease-out;          }          ::view-transition-new(root) {            animation: gif-reveal 2.5s cubic-bezier(0.4, 0, 0.2, 1);            mask-image: url('${url}');            mask-size: 0%;            mask-repeat: no-repeat;            mask-position: center;          }          @keyframes fade-out {            to {              opacity: 0;            }          }          @keyframes gif-reveal {            0% {              mask-size: 0%;            }            20% {              mask-size: 35%;            }            60% {              mask-size: 35%;            }            100% {              mask-size: 300%;            }          }        }      `;    } else if (variant === 'polygon') {      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {            animation: none;          }          ::view-transition-new(root) {            animation: ${theme === 'light' ? 'wipe-in-dark' : 'wipe-in-light'} 0.4s ease-out;          }          @keyframes wipe-in-dark {            from {              clip-path: polygon(0 0, 0 0, 0 100%, 0 100%);            }            to {              clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);            }          }          @keyframes wipe-in-light {            from {              clip-path: polygon(100% 0, 100% 0, 100% 100%, 100% 100%);            }            to {              clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);            }          }        }      `;    }        if (css) {      style.textContent = css;      document.head.appendChild(style);            // Clean up animation styles after transition      setTimeout(() => {        const styleEl = document.getElementById(styleId);        if (styleEl) {          styleEl.remove();        }      }, 3000);    }        // Call the onClick handler if provided    onClick?.();  }, [onClick, variant, start, url, theme]);  return (    <Button      variant="outline"      size={showLabel ? 'default' : 'icon'}      onClick={handleClick}      className={cn(        'relative overflow-hidden transition-all',        showLabel && 'gap-2',        className      )}      aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} theme`}    >      {theme === 'light' ? (        <Sun className="h-[1.2rem] w-[1.2rem]" />      ) : (        <Moon className="h-[1.2rem] w-[1.2rem]" />      )}      {showLabel && (        <span className="text-sm">          {theme === 'light' ? 'Light' : 'Dark'}        </span>      )}    </Button>  );};// Export a helper hook for using with View Transitions APIexport const useThemeTransition = () => {  const startTransition = useCallback((updateFn: () => void) => {    if ('startViewTransition' in document) {      (document as any).startViewTransition(updateFn);    } else {      updateFn();    }  }, []);  return { startTransition };};

Built for React applications with TypeScript and Next.js. Uses the modern View Transitions API for hardware-accelerated animations that feel native. The transitions aren't random—they use precise masking and clip-path animations that create visual continuity. Works with any theme management solution including next-themes, custom contexts, or global state.

Why most theme toggles feel abrupt

Developers just toggle a CSS class and call it done. Maybe they add a basic fade if they're being fancy. The problem? Users lose visual context during the transition. Their brain needs to reprocess the entire interface. It feels like switching between different apps, not different versions of the same app.

The View Transitions API solves this by creating smooth morphing animations between DOM states. The expanding circle creates anticipation and guides the eye. The blur effects add depth and sophistication. Custom GIF masks let you match your brand personality. It's not just a toggle—it's a mini-experience.

This component handles the complex API integration, fallback management, and animation cleanup automatically. Multiple variants ensure you can match any design aesthetic while maintaining smooth performance across devices.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/theme-toggle-button.json

npx shadcn@latest add https://www.shadcn.io/registry/theme-toggle-button.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/theme-toggle-button.json

bunx shadcn@latest add https://www.shadcn.io/registry/theme-toggle-button.json

Examples

GIF Mask Animations

Loading component...

'use client'import React, { useCallback, useEffect, useState } from "react"import { useTheme } from 'next-themes'import { useSettings } from '@/hooks/useSettings'import type { Mode } from '@/contexts/settingsContext'import { ThemeToggleButton, useThemeTransition } from "@/components/ui/shadcn-io/theme-toggle-button"const ThemeToggleGifDemo = () => {  const { setTheme } = useTheme()  const { settings, updateSettings } = useSettings()  const { startTransition } = useThemeTransition()  const [mounted, setMounted] = useState(false)  useEffect(() => {    setMounted(true)  }, [])  const handleThemeToggle = useCallback(() => {    const newMode: Mode = settings.mode === 'dark' ? 'light' : 'dark'        startTransition(() => {      const updatedSettings = {        ...settings,        mode: newMode,        theme: {          ...settings.theme,          styles: {            light: settings.theme.styles?.light || {},            dark: settings.theme.styles?.dark || {}          }        }      }      updateSettings(updatedSettings)      setTheme(newMode)    })  }, [settings, updateSettings, setTheme, startTransition])  const currentTheme = settings.mode === 'system' ? 'light' : settings.mode as 'light' | 'dark'  if (!mounted) {    return null  }  return (    <div className="flex items-center justify-center gap-4 p-8">      {/* GIF 1 */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="gif"          url="https://media.giphy.com/media/KBbr4hHl9DSahKvInO/giphy.gif?cid=790b76112m5eeeydoe7et0cr3j3ekb1erunxozyshuhxx2vl&ep=v1_stickers_search&rid=giphy.gif&ct=s"        />        <span className="text-xs text-muted-foreground">GIF</span>      </div>      {/* GIF 2 */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="gif"          url="https://media.giphy.com/media/5PncuvcXbBuIZcSiQo/giphy.gif?cid=ecf05e47j7vdjtytp3fu84rslaivdun4zvfhej6wlvl6qqsz&ep=v1_stickers_search&rid=giphy.gif&ct=s"        />        <span className="text-xs text-muted-foreground">GIF</span>      </div>      {/* GIF 3 */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="gif"          url="https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExZ3JwcXdzcHd5MW92NWprZXVpcTBtNXM5cG9obWh0N3I4NzFpaDE3byZlcD12MV9zdGlja2Vyc19zZWFyY2gmY3Q9cw/WgsVx6C4N8tjy/giphy.gif"        />        <span className="text-xs text-muted-foreground">GIF</span>      </div>      {/* GIF 4 */}      <div className="flex flex-col items-center gap-3">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="gif"          url="https://media.giphy.com/media/ArfrRmFCzYXsC6etQX/giphy.gif?cid=ecf05e47kn81xmnuc9vd5g6p5xyjt14zzd3dzwso6iwgpvy3&ep=v1_stickers_search&rid=giphy.gif&ct=s"        />        <span className="text-xs text-muted-foreground">GIF</span>      </div>    </div>  )}export default ThemeToggleGifDemo

'use client';import { Moon, Sun } from 'lucide-react';import { useCallback } from 'react';import { Button } from '@/components/ui/button';import { cn } from '@/lib/utils';type AnimationVariant =   | 'circle'   | 'circle-blur'   | 'gif'  | 'polygon';type StartPosition =   | 'center'   | 'top-left'   | 'top-right'   | 'bottom-left'   | 'bottom-right';export interface ThemeToggleButtonProps {  theme?: 'light' | 'dark';  showLabel?: boolean;  variant?: AnimationVariant;  start?: StartPosition;  url?: string; // For gif variant  className?: string;  onClick?: () => void;}export const ThemeToggleButton = ({  theme = 'light',  showLabel = false,  variant = 'circle',  start = 'center',  url,  className,  onClick,}: ThemeToggleButtonProps) => {    const handleClick = useCallback(() => {    // Inject animation styles for this specific transition    const styleId = `theme-transition-${Date.now()}`;    const style = document.createElement('style');    style.id = styleId;        // Generate animation CSS based on variant    let css = '';    const positions = {      center: 'center',      'top-left': 'top left',      'top-right': 'top right',      'bottom-left': 'bottom left',      'bottom-right': 'bottom right',    };        if (variant === 'circle') {      const cx = start === 'center' ? '50' : start.includes('left') ? '0' : '100';      const cy = start === 'center' ? '50' : start.includes('top') ? '0' : '100';      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {             animation: none;          }          ::view-transition-new(root) {            animation: circle-expand 0.4s ease-out;            transform-origin: ${positions[start]};          }          @keyframes circle-expand {            from {              clip-path: circle(0% at ${cx}% ${cy}%);            }            to {              clip-path: circle(150% at ${cx}% ${cy}%);            }          }        }      `;    } else if (variant === 'circle-blur') {      const cx = start === 'center' ? '50' : start.includes('left') ? '0' : '100';      const cy = start === 'center' ? '50' : start.includes('top') ? '0' : '100';      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {             animation: none;          }          ::view-transition-new(root) {            animation: circle-blur-expand 0.5s ease-out;            transform-origin: ${positions[start]};            filter: blur(0);          }          @keyframes circle-blur-expand {            from {              clip-path: circle(0% at ${cx}% ${cy}%);              filter: blur(4px);            }            to {              clip-path: circle(150% at ${cx}% ${cy}%);              filter: blur(0);            }          }        }      `;    } else if (variant === 'gif' && url) {      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {            animation: fade-out 0.4s ease-out;          }          ::view-transition-new(root) {            animation: gif-reveal 2.5s cubic-bezier(0.4, 0, 0.2, 1);            mask-image: url('${url}');            mask-size: 0%;            mask-repeat: no-repeat;            mask-position: center;          }          @keyframes fade-out {            to {              opacity: 0;            }          }          @keyframes gif-reveal {            0% {              mask-size: 0%;            }            20% {              mask-size: 35%;            }            60% {              mask-size: 35%;            }            100% {              mask-size: 300%;            }          }        }      `;    } else if (variant === 'polygon') {      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {            animation: none;          }          ::view-transition-new(root) {            animation: ${theme === 'light' ? 'wipe-in-dark' : 'wipe-in-light'} 0.4s ease-out;          }          @keyframes wipe-in-dark {            from {              clip-path: polygon(0 0, 0 0, 0 100%, 0 100%);            }            to {              clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);            }          }          @keyframes wipe-in-light {            from {              clip-path: polygon(100% 0, 100% 0, 100% 100%, 100% 100%);            }            to {              clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);            }          }        }      `;    }        if (css) {      style.textContent = css;      document.head.appendChild(style);            // Clean up animation styles after transition      setTimeout(() => {        const styleEl = document.getElementById(styleId);        if (styleEl) {          styleEl.remove();        }      }, 3000);    }        // Call the onClick handler if provided    onClick?.();  }, [onClick, variant, start, url, theme]);  return (    <Button      variant="outline"      size={showLabel ? 'default' : 'icon'}      onClick={handleClick}      className={cn(        'relative overflow-hidden transition-all',        showLabel && 'gap-2',        className      )}      aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} theme`}    >      {theme === 'light' ? (        <Sun className="h-[1.2rem] w-[1.2rem]" />      ) : (        <Moon className="h-[1.2rem] w-[1.2rem]" />      )}      {showLabel && (        <span className="text-sm">          {theme === 'light' ? 'Light' : 'Dark'}        </span>      )}    </Button>  );};// Export a helper hook for using with View Transitions APIexport const useThemeTransition = () => {  const startTransition = useCallback((updateFn: () => void) => {    if ('startViewTransition' in document) {      (document as any).startViewTransition(updateFn);    } else {      updateFn();    }  }, []);  return { startTransition };};

Animation Positions

Circle animations can start from different positions for directional effects:

Loading component...

'use client'import React, { useCallback, useEffect, useState } from "react"import { useTheme } from 'next-themes'import { useSettings } from '@/hooks/useSettings'import type { Mode } from '@/contexts/settingsContext'import { ThemeToggleButton, useThemeTransition } from "@/components/ui/shadcn-io/theme-toggle-button"const ThemeTogglePositionsDemo = () => {  const { setTheme } = useTheme()  const { settings, updateSettings } = useSettings()  const { startTransition } = useThemeTransition()  const [mounted, setMounted] = useState(false)  useEffect(() => {    setMounted(true)  }, [])  const handleThemeToggle = useCallback(() => {    const newMode: Mode = settings.mode === 'dark' ? 'light' : 'dark'        startTransition(() => {      const updatedSettings = {        ...settings,        mode: newMode,        theme: {          ...settings.theme,          styles: {            light: settings.theme.styles?.light || {},            dark: settings.theme.styles?.dark || {}          }        }      }      updateSettings(updatedSettings)      setTheme(newMode)    })  }, [settings, updateSettings, setTheme, startTransition])  const currentTheme = settings.mode === 'system' ? 'light' : settings.mode as 'light' | 'dark'  if (!mounted) {    return null  }  return (    <div className="grid grid-cols-3 gap-4 p-8 max-w-md mx-auto">      {/* Top row */}      <div className="flex flex-col items-center gap-2">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="circle"          start="top-left"        />        <span className="text-xs text-muted-foreground">Top Left</span>      </div>            <div className="flex flex-col items-center gap-2">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="circle"          start="center"        />        <span className="text-xs text-muted-foreground">Center</span>      </div>            <div className="flex flex-col items-center gap-2">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="circle"          start="top-right"        />        <span className="text-xs text-muted-foreground">Top Right</span>      </div>      {/* Middle row - empty spaces for visual balance */}      <div></div>      <div></div>      <div></div>      {/* Bottom row */}      <div className="flex flex-col items-center gap-2">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="circle"          start="bottom-left"        />        <span className="text-xs text-muted-foreground">Bottom Left</span>      </div>            <div></div>            <div className="flex flex-col items-center gap-2">        <ThemeToggleButton           theme={currentTheme}          onClick={handleThemeToggle}          variant="circle"          start="bottom-right"        />        <span className="text-xs text-muted-foreground">Bottom Right</span>      </div>    </div>  )}export default ThemeTogglePositionsDemo

'use client';import { Moon, Sun } from 'lucide-react';import { useCallback } from 'react';import { Button } from '@/components/ui/button';import { cn } from '@/lib/utils';type AnimationVariant =   | 'circle'   | 'circle-blur'   | 'gif'  | 'polygon';type StartPosition =   | 'center'   | 'top-left'   | 'top-right'   | 'bottom-left'   | 'bottom-right';export interface ThemeToggleButtonProps {  theme?: 'light' | 'dark';  showLabel?: boolean;  variant?: AnimationVariant;  start?: StartPosition;  url?: string; // For gif variant  className?: string;  onClick?: () => void;}export const ThemeToggleButton = ({  theme = 'light',  showLabel = false,  variant = 'circle',  start = 'center',  url,  className,  onClick,}: ThemeToggleButtonProps) => {    const handleClick = useCallback(() => {    // Inject animation styles for this specific transition    const styleId = `theme-transition-${Date.now()}`;    const style = document.createElement('style');    style.id = styleId;        // Generate animation CSS based on variant    let css = '';    const positions = {      center: 'center',      'top-left': 'top left',      'top-right': 'top right',      'bottom-left': 'bottom left',      'bottom-right': 'bottom right',    };        if (variant === 'circle') {      const cx = start === 'center' ? '50' : start.includes('left') ? '0' : '100';      const cy = start === 'center' ? '50' : start.includes('top') ? '0' : '100';      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {             animation: none;          }          ::view-transition-new(root) {            animation: circle-expand 0.4s ease-out;            transform-origin: ${positions[start]};          }          @keyframes circle-expand {            from {              clip-path: circle(0% at ${cx}% ${cy}%);            }            to {              clip-path: circle(150% at ${cx}% ${cy}%);            }          }        }      `;    } else if (variant === 'circle-blur') {      const cx = start === 'center' ? '50' : start.includes('left') ? '0' : '100';      const cy = start === 'center' ? '50' : start.includes('top') ? '0' : '100';      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {             animation: none;          }          ::view-transition-new(root) {            animation: circle-blur-expand 0.5s ease-out;            transform-origin: ${positions[start]};            filter: blur(0);          }          @keyframes circle-blur-expand {            from {              clip-path: circle(0% at ${cx}% ${cy}%);              filter: blur(4px);            }            to {              clip-path: circle(150% at ${cx}% ${cy}%);              filter: blur(0);            }          }        }      `;    } else if (variant === 'gif' && url) {      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {            animation: fade-out 0.4s ease-out;          }          ::view-transition-new(root) {            animation: gif-reveal 2.5s cubic-bezier(0.4, 0, 0.2, 1);            mask-image: url('${url}');            mask-size: 0%;            mask-repeat: no-repeat;            mask-position: center;          }          @keyframes fade-out {            to {              opacity: 0;            }          }          @keyframes gif-reveal {            0% {              mask-size: 0%;            }            20% {              mask-size: 35%;            }            60% {              mask-size: 35%;            }            100% {              mask-size: 300%;            }          }        }      `;    } else if (variant === 'polygon') {      css = `        @supports (view-transition-name: root) {          ::view-transition-old(root) {            animation: none;          }          ::view-transition-new(root) {            animation: ${theme === 'light' ? 'wipe-in-dark' : 'wipe-in-light'} 0.4s ease-out;          }          @keyframes wipe-in-dark {            from {              clip-path: polygon(0 0, 0 0, 0 100%, 0 100%);            }            to {              clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);            }          }          @keyframes wipe-in-light {            from {              clip-path: polygon(100% 0, 100% 0, 100% 100%, 100% 100%);            }            to {              clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);            }          }        }      `;    }        if (css) {      style.textContent = css;      document.head.appendChild(style);            // Clean up animation styles after transition      setTimeout(() => {        const styleEl = document.getElementById(styleId);        if (styleEl) {          styleEl.remove();        }      }, 3000);    }        // Call the onClick handler if provided    onClick?.();  }, [onClick, variant, start, url, theme]);  return (    <Button      variant="outline"      size={showLabel ? 'default' : 'icon'}      onClick={handleClick}      className={cn(        'relative overflow-hidden transition-all',        showLabel && 'gap-2',        className      )}      aria-label={`Switch to ${theme === 'light' ? 'dark' : 'light'} theme`}    >      {theme === 'light' ? (        <Sun className="h-[1.2rem] w-[1.2rem]" />      ) : (        <Moon className="h-[1.2rem] w-[1.2rem]" />      )}      {showLabel && (        <span className="text-sm">          {theme === 'light' ? 'Light' : 'Dark'}        </span>      )}    </Button>  );};// Export a helper hook for using with View Transitions APIexport const useThemeTransition = () => {  const startTransition = useCallback((updateFn: () => void) => {    if ('startViewTransition' in document) {      (document as any).startViewTransition(updateFn);    } else {      updateFn();    }  }, []);  return { startTransition };};

Features

View Transitions API integration for hardware-accelerated theme switching animations
Multiple animation variants including circle, blur, polygon and custom GIF masks
Flexible positioning with animations starting from center, corners, or edges
Framework agnostic works with any theme management solution (next-themes, custom context)
TypeScript definitions with complete interface definitions and IntelliSense
Accessible controls with proper ARIA labels and keyboard navigation support
Automatic fallbacks for browsers without View Transitions API support
Performance optimized with dynamic CSS injection and automatic cleanup

Use Cases

This free open source React component works perfectly for:

Navigation headers - Elegant theme switching for Next.js applications
Settings interfaces - Beautiful preference controls using TypeScript
Admin dashboards - Professional theme buttons with shadcn/ui integration
Landing pages - Memorable user experiences with custom animations
Mobile apps - Native-feeling theme toggles that respond smoothly
Creative portfolios - Artistic transitions that showcase attention to detail

API Reference

ThemeToggleButton

The main component for animated theme switching with View Transitions.

Prop	Type	Default	Description
`theme`	`'light' \| 'dark'`	`'light'`	Current theme state
`onClick`	`() => void`	-	Click handler for theme toggle
`variant`	`'circle' \| 'circle-blur' \| 'gif' \| 'polygon'`	`'circle'`	Animation variant to use
`start`	`'center' \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`	`'center'`	Starting position for circle animations
`showLabel`	`boolean`	`false`	Show text label next to icon
`url`	`string`	-	URL of GIF to use as mask (required for gif variant)
`className`	`string`	-	Additional CSS classes
`disabled`	`boolean`	`false`	Disables button and prevents animations
`...props`	`ButtonHTMLAttributes`	-	All native button props supported

Animation Variant Specifications

Variant	Effect	Performance	Use Case
`circle`	Expanding circle mask	Excellent	Clean, minimal interfaces
`circle-blur`	Circle with gaussian blur	Very good	Soft, premium feel
`polygon`	Diagonal clip-path wipe	Excellent	Modern, geometric designs
`gif`	Custom GIF as mask	Good	Brand-specific animations

Position Specifications

Position	Origin Point	Visual Effect
`center`	Button center	Balanced expansion
`top-left`	Upper left corner	Diagonal sweep right-down
`top-right`	Upper right corner	Diagonal sweep left-down
`bottom-left`	Lower left corner	Diagonal sweep right-up
`bottom-right`	Lower right corner	Diagonal sweep left-up

useThemeTransition Hook

Helper hook that wraps the View Transitions API with automatic fallbacks:

const { startTransition } = useThemeTransition();

// Use it to wrap your theme update
startTransition(() => {
  setTheme(newTheme);
  // Any other DOM updates
});

Browser Support

View Transitions API support status:

Chrome/Edge 111+ - Full animation support with hardware acceleration
Opera 97+ - Complete feature set with smooth performance
Safari 18+ - Experimental support, enable in Feature Flags
Firefox - Not yet supported, gracefully falls back to instant toggle

Note: In unsupported browsers, the component automatically falls back to immediate theme switching without animations.

Common gotchas

Animation flickering on fast clicks: Rapid theme toggling can cause overlapping transitions. The component debounces clicks automatically, but very fast clicking might create visual conflicts in some browsers.

Custom theme properties not transitioning: The View Transitions API only animates CSS properties that can be interpolated. Custom properties using discrete values (like font families) won't animate smoothly.

GIF performance impact: Custom GIF masks can be resource-intensive, especially large or high-framerate GIFs. Consider optimizing GIFs for web use or using simpler animations for better performance.

Z-index layering during transition: The transition creates a temporary overlay that might interfere with high z-index elements like modals or dropdowns. Ensure proper stacking context for complex layouts.

Theme context timing: Make sure theme updates happen inside the startTransition callback for proper synchronization. Updating theme state before or after the transition can cause visual inconsistencies.

Safari flag requirement: Safari users need to manually enable View Transitions in Settings > Advanced > Feature Flags. Consider showing instructions or using feature detection to inform users.

Explore other interactive button components for React applications:

React Theme Toggle Button

Why most theme toggles feel abrupt

Installation

Examples

GIF Mask Animations

Animation Positions

Features

Use Cases

API Reference

ThemeToggleButton

Animation Variant Specifications

Position Specifications

useThemeTransition Hook

Browser Support

Common gotchas

You might also like

Icon Button

Liquid Button

Ripple Button

Flip Button

Questions developers actually ask

On this page

React Theme Toggle Button