@tavosud/sky-theme

v1.0.5

Published

8 days ago

Ultra-lightweight, SSR-safe, zero-dependency dark mode and theme manager for React.

0High
0Medium
0Low

tavosud

react theme dark-mode light-mode ssr typescript zero-deps context provider

Sky Theme

Ultra-lightweight, SSR-safe, zero-dependency dark mode and theme manager for React.

Features

Zero dependencies — only React
SSR-safe — no hydration flash
TypeScript — full type definitions
Scoped themes — multiple providers support
Professional styles — built-in gradients and glassmorphism
Accessible — ARIA labels, keyboard navigation

Installation

npm install @tavosud/sky-theme

Quick Start

1. Import styles (optional)

For professional dark mode with gradients and glassmorphism:

import '@tavosud/sky-theme/styles';

Or in CSS:

@import '@tavosud/sky-theme/styles';

2. Add the anti-flash script

To prevent flash of wrong theme on SSR, add this to your HTML <head>:

<script>
  (function(){
    try{
      var s=localStorage.getItem('sky-theme');
      var p=window.matchMedia('(prefers-color-scheme: dark)').matches;
      var d=s==='dark'||(s!=='light'&&(s==='system'||!s)&&p);
      d?document.documentElement.classList.add('dark'):document.documentElement.classList.remove('dark');
    }catch(e){}
  })();
</script>

Or use the React component (Next.js, Remix, etc.):

import { ThemeScript } from '@tavosud/sky-theme';

// In your layout root
<ThemeScript storageKey="sky-theme" defaultMode="system" />

3. Wrap your app

import { ThemeProvider, ThemeButton } from '@tavosud/sky-theme';

export function App() {
  return (
    <ThemeProvider defaultMode="system">
      <Navbar />
      <Content />
    </ThemeProvider>
  );
}

4. Use the hook

import { useTheme } from '@tavosud/sky-theme';

function MyComponent() {
  const { resolvedTheme } = useTheme();
  
  return (
    <div className="sky-surface">
      Current theme: {resolvedTheme}
    </div>
  );
}

Built-in CSS Classes

Import @tavosud/sky-theme/styles for professional styling:

| Class | Description | |-------|-------------| | .sky-surface | Background with gradient | | .sky-glass | Glassmorphism effect (blur + transparency) | | .sky-card | Card with shadow and border | | .sky-border | Adaptive border color | | .sky-text | Primary text color | | .sky-text-muted | Secondary text color |

API Reference

ThemeProvider

| Prop | Type | Default | Description | |------|------|---------|-------------| | defaultMode | 'light' \| 'dark' \| 'system' | 'system' | Initial mode | | storageKey | string | 'sky-theme' | localStorage key | | persist | boolean | true | Persist to localStorage | | scope | string | 'default' | Provider scope (for multiple themes) | | classMap | Record<string, string> | { dark: 'dark' } | Map modes to CSS classes | | onThemeChange | (theme: string) => void | - | Callback on change | | transitionClassName | string | - | Class added during transitions |

useTheme

const { mode, resolvedTheme, toggle, setMode } = useTheme();

mode — current setting ('light', 'dark', 'system', or custom)
resolvedTheme — actual theme ('light' or 'dark', never 'system')
toggle() — cycle to next mode
setMode(mode) — set specific mode

ThemeButton

import { ThemeButton } from '@tavosud/sky-theme';

// With label
<ThemeButton showLabel />

// With custom styles
<ThemeButton style={{ color: 'red' }} />

License

MIT