season-lib-theme

A lightweight and performant React library for adding dynamic, CSS-based seasonal themes and particle animations to your web applications. Automatically detects the current season and provides customizable particle effects like falling snow, autumn leaves, spring petals, and summer glows.

Features

• Automatic Season Detection: Based on the user's system date and configurable hemisphere.
• High-Performance CSS Animations: Utilizes mask-image, transform, and opacity for smooth, GPU-accelerated particle effects.
• Customizable Particles: Includes detailed SVG snowflakes and maple leaves, with randomized sizes, opacities, and colors.
• Theming Context: Provides a <SeasonalProvider /> component and a useSeason hook for easy integration and season overriding.
• TypeScript Support: Fully typed for a robust development experience.
• Next.js App Router Compatible: Designed with "use client" directives for seamless use in Next.js Server Components environments.
• pointer-events: none: Ensures animations do not interfere with user interaction.

Installation

npm install season-lib-theme

or with yarn:

yarn add season-lib-theme

or with pnpm:

pnpm add season-lib-theme

Usage

1. Wrap your application with SeasonalProvider

To enable seasonal effects across your application, wrap your root component (e.g., in main.tsx for Vite or layout.tsx for Next.js App Router) with the SeasonalProvider.

// src/main.tsx (or equivalent root file)
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { SeasonalProvider } from 'season-lib-theme';
// Import the seasonal effects CSS
import 'season-lib-theme/style.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <SeasonalProvider>
      <App />
    </SeasonalProvider>
  </React.StrictMode>,
);

2. Access the current season with useSeason

You can use the useSeason hook in any child component of SeasonalProvider to access the currently detected season.

"use client"; // Required for client-side hooks in Next.

import { useSeason } from 'season-lib-theme';

function ThemedComponent() {
  const { season } = useSeason(); // Returns 'winter', 'spring', 'summer', or 'autumn'

  return (
    <div className={`my-component ${season}`}>
    </div>
  );
}

export default ThemedComponent;

3. Overriding the Season

You can manually set the season by passing the season prop to the SeasonalProvider. This is useful for testing or specific themed pages.

<SeasonalProvider season="winter">
  {/* Your application content will always show winter effects */}
  <App />
</SeasonalProvider>

4. Specifying Hemisphere

By default, the library uses the Northern Hemisphere's seasonal calendar. You can change this using the hemisphere prop:

<SeasonalProvider hemisphere="S">
  {/* Application will use Southern Hemisphere seasons */}
  <App />
</SeasonalProvider>

Development

# Install dependencies
npm install

# Run the development server
npm run dev

# Build the library for production
npm run build

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License