Getting Started with BlackMagic.js

BlackMagic.js is the world's first truly automatic dark mode framework. It requires zero configuration and automatically ensures WCAG 2.1 accessibility compliance.

Installation

NPM Installation

Terminal
npm install blackmagic-js
JavaScript (ES6 Modules)
import BlackMagic from 'blackmagic-js';

const darkMode = new BlackMagic();
darkMode.toggle();

CDN Installation

HTML
<script src="https://cdn.jsdelivr.net/npm/blackmagic-js@latest"></script>
<script>
  const blackMagic = new BlackMagic();
  blackMagic.toggle();
</script>

Basic Usage

The simplest way to add dark mode to your website:

JavaScript
// Initialize BlackMagic
const blackMagic = new BlackMagic();

// Toggle between light and dark themes
document.getElementById('darkModeToggle').addEventListener('click', () => {
    blackMagic.toggle();
});

Configuration Options

BlackMagic.js works perfectly with zero configuration, but you can customize it:

JavaScript
const blackMagic = new BlackMagic({
    backgroundColor: '#1a1a1a',    // Custom dark background color
    factor: 0.4,                  // Color adjustment intensity (0-1)
    themeClass: 'custom-dark',    // Use CSS class instead of inline styles
    cookieName: 'theme',          // Custom cookie name
    cookieDuration: 365,          // Cookie expiration in days
    localStorageKey: 'darkmode',  // Custom localStorage key
    autoSwitch: true,             // Apply saved theme on page load
    currentTheme: 'light'         // Initial theme ('light' or 'dark')
});

Configuration Details

API Reference

Methods

toggle()

Switches between light and dark themes.

blackMagic.toggle();

applyTheme(theme)

Applies a specific theme ('light' or 'dark').

blackMagic.applyTheme('dark');
blackMagic.applyTheme('light');

getCurrentTheme()

Returns the current theme ('light' or 'dark').

const currentTheme = blackMagic.getCurrentTheme();
console.log(currentTheme); // 'light' or 'dark'

saveTheme(theme)

Saves theme preference to cookies and localStorage.

blackMagic.saveTheme('dark');

getStoredTheme()

Retrieves saved theme preference.

const savedTheme = blackMagic.getStoredTheme();
console.log(savedTheme); // 'light', 'dark', or null

Advanced Usage

Using with CSS Classes

Instead of inline styles, you can use CSS classes:

JavaScript
const blackMagic = new BlackMagic({
    themeClass: 'dark-theme'
});
CSS
body.dark-theme {
    background-color: #1a1a1a;
    color: #e0e0e0;
}

body.dark-theme .card {
    background-color: #2a2a2a;
    border-color: #404040;
}

Custom Color Adjustment

Fine-tune how aggressively colors are adjusted:

// Subtle adjustment (good for websites with light backgrounds)
const subtle = new BlackMagic({ factor: 0.2 });

// Standard adjustment (balanced, recommended)
const standard = new BlackMagic({ factor: 0.4 });

// Aggressive adjustment (good for websites with many colors)
const aggressive = new BlackMagic({ factor: 0.7 });

Multiple Instances

You can create multiple BlackMagic instances with different configurations:

// Main site dark mode
const mainDarkMode = new BlackMagic({
    backgroundColor: '#1a1a1a',
    cookieName: 'site-theme'
});

// Modal dark mode with different settings
const modalDarkMode = new BlackMagic({
    backgroundColor: '#2d1b69',
    factor: 0.6,
    autoSwitch: false
});

Browser Support

BlackMagic.js works across all modern browsers:

Feature Detection

BlackMagic.js includes graceful fallbacks:

Accessibility

BlackMagic.js is designed with accessibility as a core feature:

WCAG 2.1 Compliance

Color Science

BlackMagic uses advanced color algorithms:

Performance

BlackMagic.js is optimized for speed and efficiency:

Benchmarks

Optimization Features

Troubleshooting

Common Issues

Dark mode doesn't apply to all elements

This usually happens when elements have very specific CSS selectors. Try increasing the factor:

const blackMagic = new BlackMagic({ factor: 0.6 });

Theme doesn't persist across pages

Make sure cookies are enabled and you're not in incognito mode. Check your cookie settings:

const blackMagic = new BlackMagic({
    cookieDuration: 365,  // Persist for 1 year
    cookieName: 'custom-theme-name'
});

Performance issues on large pages

For pages with thousands of elements, consider using CSS classes:

const blackMagic = new BlackMagic({
    themeClass: 'dark-mode'  // Use CSS instead of inline styles
});

Debug Mode

Enable console logging to debug issues:

// Check current theme
console.log('Current theme:', blackMagic.getCurrentTheme());

// Check stored theme
console.log('Stored theme:', blackMagic.getStoredTheme());

// Check if cookies work
document.cookie = 'test=value';
console.log('Cookies enabled:', document.cookie.includes('test=value'));

Migration Guide

From CSS-based Dark Mode

Replace manual CSS with BlackMagic:

Before (Manual CSS)
/* Remove hundreds of lines like this */
.dark-mode .button { color: #fff; background: #333; }
.dark-mode .text { color: #e0e0e0; }
.dark-mode .card { background: #2a2a2a; }
After (BlackMagic)
// Replace with 3 lines
const blackMagic = new BlackMagic();
button.addEventListener('click', () => blackMagic.toggle());

From Other Dark Mode Libraries

BlackMagic.js uses similar API patterns:

// Most libraries
darkMode.toggle();

// BlackMagic (same API!)
blackMagic.toggle();

Contributing

BlackMagic.js is open source and welcomes contributions!

Development Setup

git clone https://github.com/LucAngevare/BlackMagic-js.git
cd BlackMagic-js
npm install
npm run dev

Contributing Guidelines

Reporting Issues

Found a bug? Report it on GitHub with:

Need More Help?

Join our community for support and discussions:

Report Issues