Tailwind Theme Switch

adnanalemran

tailwind-theme-cursor-switch

A Tailwind CSS theme switcher that toggles dark/light mode when clicking in the top-left corner of the screen. Perfect for creating a subtle, cursor-based theme switching experience in your web applications.

Features

🔄 Toggle theme by clicking in the top-left corner (50x50px zone)
🌓 Automatically syncs with system dark/light mode preference
💾 Persists theme preference in localStorage
🔄 Syncs theme across browser tabs
🎯 Zero dependencies (except Tailwind CSS)
📦 ESM-compatible
🎨 Works with Tailwind CSS's darkMode: 'class' configuration

Installation

npm install tailwind-theme-cursor-switch

Usage

First, ensure your Tailwind CSS configuration has darkMode: 'class':

// tailwind.config.js
module.exports = {
  darkMode: 'class',
  // ... rest of your config
}

Import and initialize the theme switcher in your JavaScript/TypeScript:

// Using ES modules
import { initThemeCursorToggle } from 'tailwind-theme-cursor-switch';

// Initialize the theme switcher
initThemeCursorToggle();

Or using CommonJS:

const { initThemeCursorToggle } = require('tailwind-theme-cursor-switch');

initThemeCursorToggle();

That's it! The theme will now toggle when users click in the top-left corner of the screen.

React Usage

You can use this package in React applications in two ways:

Basic Usage (Recommended)

Initialize the theme switcher in your app's entry point (e.g., main.tsx or App.tsx):

// src/main.tsx or src/App.tsx
import { initThemeCursorToggle } from 'tailwind-theme-cursor-switch';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    initThemeCursorToggle();
  }, []);

  return (
    // Your app content
  );
}

Custom Hook Usage

Create a custom hook for more control:

// src/hooks/useThemeCursor.ts
import { useEffect } from 'react';
import { initThemeCursorToggle, Theme } from 'tailwind-theme-cursor-switch';

export function useThemeCursor() {
  useEffect(() => {
    const cleanup = initThemeCursorToggle();
    return () => {
      // Cleanup event listeners if needed
      cleanup?.();
    };
  }, []);
}

// Usage in your component:
function App() {
  useThemeCursor();
  return (
    // Your app content
  );
}

With Next.js

For Next.js applications, initialize in your _app.tsx or layout.tsx:

// src/app/layout.tsx (App Router)
'use client';

import { useEffect } from 'react';
import { initThemeCursorToggle } from 'tailwind-theme-cursor-switch';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  useEffect(() => {
    initThemeCursorToggle();
  }, []);

  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Or with Pages Router:

// src/pages/_app.tsx
import { useEffect } from 'react';
import { initThemeCursorToggle } from 'tailwind-theme-cursor-switch';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    initThemeCursorToggle();
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

React + Tailwind Setup

Ensure your Tailwind configuration is set up correctly:

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'class',
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
  ],
  // ... rest of your config
}

Add dark mode styles to your global CSS:

/* src/index.css or src/styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Optional: Add smooth transitions for theme changes */
* {
  @apply transition-colors duration-200;
}

How it Works

The package creates a 50x50px trigger zone in the top-left corner of the screen
When a user clicks within this zone, the theme toggles between dark and light mode
The theme preference is stored in localStorage under the key 'tailwind-theme-preference'
On initial load, it checks localStorage for a saved preference, falling back to system preference
Theme changes are synced across browser tabs using the storage event
The package automatically handles adding/removing the dark class on the documentElement

TypeScript Support

The package includes TypeScript definitions. The main type export is:

type Theme = 'dark' | 'light';

Browser Support

This package works in all modern browsers that support:

ES Modules
localStorage
matchMedia
classList

License

MIT

Top categories