BismillahCSS LogoBismillahCSS
HomeDocumentation

Dark Mode

Implement dark mode easily in your BismillahCSS projects. Support system preferences and user toggling.

Understanding Dark Mode

Dark mode provides an alternative color scheme for your application, improving accessibility and reducing eye strain for users in low-light environments. BismillahCSS makes it simple to implement with the `dark:` variant.

💡 In BismillahCSS

Use the `dark:` prefix to apply styles that only activate when dark mode is enabled on the parent element.

Dark Mode Strategies

â‘  CSS Media Query

Automatically follow the system's dark mode preference using `prefers-color-scheme`

<!-- Add dark class when system prefers dark mode -->
<html class="dark">
  <!-- Your content -->
</html>

✅ Best for: Sites that should follow system preferences

â‘¡ Class-based (Recommended)

Manually toggle a class to control dark mode

<!-- Light mode -->
<html>
  <!-- Your content -->
</html>

<!-- Dark mode -->
<html class="dark">
  <!-- Your content -->
</html>

✅ Best for: Full user control over theme preference

â‘¢ LocalStorage Persistence

Save the user's preference and apply it on page load

✅ Best for: Remembering user's theme choice across visits

Basic Dark Mode Usage

Use the `dark:` variant to specify dark mode styles:

<!-- Light mode background, dark mode background -->
<div class="bismillah-bg-white dark:bismillah-bg-gray-900">
  <!-- Light mode text, dark mode text -->
  <h1 class="bismillah-text-gray-900 dark:bismillah-text-white">
    Welcome
  </h1>
  
  <!-- Light mode paragraph text, dark mode lighter text -->
  <p class="bismillah-text-gray-600 dark:bismillah-text-gray-300">
    This is a responsive dark mode example
  </p>
</div>

Complete Dark Mode Example

<!DOCTYPE html>
<html lang="en" class="dark">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Dark Mode Example</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bismillahcss@latest/dist/bismillah.min.css">
</head>
<body class="bismillah-bg-white dark:bismillah-bg-gray-900 bismillah-text-gray-900 dark:bismillah-text-white transition-colors">
  
  <!-- Navigation -->
  <nav class="bismillah-bg-gray-100 dark:bismillah-bg-gray-800 bismillah-p-4 bismillah-shadow">
    <div class="bismillah-flex bismillah-items-center bismillah-justify-between">
      <h1 class="bismillah-text-xl bismillah-font-bold">Logo</h1>
      <button onclick="toggleDarkMode()" class="bismillah-px-4 bismillah-py-2 bismillah-bg-gray-200 dark:bismillah-bg-gray-700 bismillah-rounded">
        🌙 Toggle Theme
      </button>
    </div>
  </nav>

  <!-- Content -->
  <main class="bismillah-container bismillah-mx-auto bismillah-px-4 bismillah-py-8">
    <h2 class="bismillah-text-3xl bismillah-font-bold bismillah-mb-4">Dark Mode Example</h2>
    
    <div class="bismillah-grid bismillah-grid-cols-1 md:bismillah-grid-cols-2 bismillah-gap-6">
      <!-- Card 1 -->
      <div class="bismillah-bg-gray-50 dark:bismillah-bg-gray-800 bismillah-rounded-lg bismillah-p-6 bismillah-shadow">
        <h3 class="bismillah-text-lg bismillah-font-bold bismillah-mb-2">Card One</h3>
        <p class="bismillah-text-gray-600 dark:bismillah-text-gray-300 bismillah-mb-4">
          This card automatically adapts to dark mode
        </p>
        <button class="bismillah-bg-blue-600 dark:bismillah-bg-blue-500 bismillah-text-white bismillah-px-4 bismillah-py-2 bismillah-rounded hover:bismillah-bg-blue-700 dark:hover:bismillah-bg-blue-600">
          Learn More
        </button>
      </div>

      <!-- Card 2 -->
      <div class="bismillah-bg-gray-50 dark:bismillah-bg-gray-800 bismillah-rounded-lg bismillah-p-6 bismillah-shadow">
        <h3 class="bismillah-text-lg bismillah-font-bold bismillah-mb-2">Card Two</h3>
        <p class="bismillah-text-gray-600 dark:bismillah-text-gray-300 bismillah-mb-4">
          All styles respond to the dark: prefix
        </p>
        <button class="bismillah-bg-green-600 dark:bismillah-bg-green-500 bismillah-text-white bismillah-px-4 bismillah-py-2 bismillah-rounded hover:bismillah-bg-green-700 dark:hover:bismillah-bg-green-600">
          Explore
        </button>
      </div>
    </div>
  </main>

  <script>
    function toggleDarkMode() {
      const html = document.documentElement;
      html.classList.toggle('dark');
      // Save preference
      localStorage.setItem('theme', html.classList.contains('dark') ? 'dark' : 'light');
    }

    // Apply saved theme on load
    window.addEventListener('load', () => {
      const saved = localStorage.getItem('theme');
      const isDark = saved === 'dark' || (!saved && window.matchMedia('(prefers-color-scheme: dark)').matches);
      if (isDark) {
        document.documentElement.classList.add('dark');
      }
    });
  </script>

</body>
</html>

Implementing Theme Toggle

Here's a complete theme toggle component:

// JavaScript to handle theme toggle
function toggleTheme() {
  const html = document.documentElement;
  const isDark = html.classList.contains('dark');
  
  // Toggle the class
  if (isDark) {
    html.classList.remove('dark');
    localStorage.setItem('theme', 'light');
  } else {
    html.classList.add('dark');
    localStorage.setItem('theme', 'dark');
  }
}

// Initialize theme on page load
function initializeTheme() {
  const html = document.documentElement;
  const saved = localStorage.getItem('theme');
  
  if (saved === 'dark') {
    html.classList.add('dark');
  } else if (saved === 'light') {
    html.classList.remove('dark');
  } else {
    // Follow system preference
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    if (prefersDark) {
      html.classList.add('dark');
    }
  }
}

// Run on page load
document.addEventListener('DOMContentLoaded', initializeTheme);

Dark Mode Color Guide

Recommended color mappings for light and dark modes:

Backgrounds

<!-- Light: white, Dark: gray-900 -->
<div class="bismillah-bg-white dark:bismillah-bg-gray-900"></div>

<!-- Light: gray-50, Dark: gray-800 -->
<div class="bismillah-bg-gray-50 dark:bismillah-bg-gray-800"></div>

<!-- Light: gray-100, Dark: gray-700 -->
<div class="bismillah-bg-gray-100 dark:bismillah-bg-gray-700"></div>

Text Colors

<!-- Primary text: gray-900 light, white dark -->
<p class="bismillah-text-gray-900 dark:bismillah-text-white"></p>

<!-- Secondary text: gray-600 light, gray-300 dark -->
<p class="bismillah-text-gray-600 dark:bismillah-text-gray-300"></p>

<!-- Tertiary text: gray-500 light, gray-400 dark -->
<p class="bismillah-text-gray-500 dark:bismillah-text-gray-400"></p>

Borders

<!-- Light: gray-200, Dark: gray-700 -->
<div class="bismillah-border bismillah-border-gray-200 dark:bismillah-border-gray-700"></div>

Accent Colors

<!-- Use the same color in both modes, optionally adjust shades -->
<button class="bismillah-bg-blue-600 dark:bismillah-bg-blue-500"></button>
<button class="bismillah-bg-green-600 dark:bismillah-bg-green-500"></button>

Real-World Examples

Card Component

<div class="bismillah-bg-white dark:bismillah-bg-gray-800 bismillah-rounded-lg bismillah-shadow-lg dark:bismillah-shadow-xl bismillah-p-6">
  <h2 class="bismillah-text-xl bismillah-font-bold bismillah-text-gray-900 dark:bismillah-text-white bismillah-mb-2">
    Card Title
  </h2>
  <p class="bismillah-text-gray-600 dark:bismillah-text-gray-300 bismillah-mb-4">
    This is a card that adapts to dark mode automatically
  </p>
  <button class="bismillah-w-full bismillah-bg-blue-600 dark:bismillah-bg-blue-500 bismillah-text-white bismillah-py-2 bismillah-rounded bismillah-font-semibold hover:bismillah-bg-blue-700 dark:hover:bismillah-bg-blue-600 transition-colors">
    Action Button
  </button>
</div>

Form Input

<input 
  type="text"
  placeholder="Enter text"
  class="
    bismillah-w-full
    bismillah-px-4
    bismillah-py-2
    bismillah-border 
    bismillah-border-gray-300
    dark:bismillah-border-gray-600
    bismillah-bg-white
    dark:bismillah-bg-gray-700
    bismillah-text-gray-900
    dark:bismillah-text-white
    placeholder:bismillah-text-gray-400
    dark:placeholder:bismillah-text-gray-500
    focus:bismillah-ring-2
    focus:bismillah-ring-blue-500
    focus:dark:bismillah-ring-blue-400
    bismillah-rounded
  "
/>

Navigation Bar

<nav class="bismillah-bg-gray-100 dark:bismillah-bg-gray-800 bismillah-border-b bismillah-border-gray-200 dark:bismillah-border-gray-700">
  <div class="bismillah-container bismillah-mx-auto bismillah-px-4">
    <div class="bismillah-flex bismillah-items-center bismillah-justify-between bismillah-py-4">
      <h1 class="bismillah-text-xl bismillah-font-bold bismillah-text-gray-900 dark:bismillah-text-white">
        Logo
      </h1>
      <div class="bismillah-flex bismillah-gap-4">
        <a href="#" class="bismillah-text-gray-600 dark:bismillah-text-gray-300 hover:bismillah-text-gray-900 dark:hover:bismillah-text-white">
          Home
        </a>
        <a href="#" class="bismillah-text-gray-600 dark:bismillah-text-gray-300 hover:bismillah-text-gray-900 dark:hover:bismillah-text-white">
          About
        </a>
      </div>
      <button onclick="toggleTheme()" class="bismillah-bg-gray-200 dark:bismillah-bg-gray-700 bismillah-text-gray-900 dark:bismillah-text-white bismillah-px-4 bismillah-py-2 bismillah-rounded">
        🌙
      </button>
    </div>
  </div>
</nav>

Configuration

Configure dark mode in your BismillahCSS config:

module.exports = {
  darkMode: 'class', // or 'media'
  theme: {
    extend: {
      // Your custom theme  
    }
  }
}

Options:

  • class: Toggle using a class on the document element
  • media: Follow system color scheme preference

Accessibility Considerations

  • Sufficient contrast: Ensure text has enough contrast in both light and dark modes.
  • Respect preferences: Check system color scheme preferences on first load.
  • Provide toggle: Allow users to manually override their system preference.
  • Use semantic colors: Maintain consistent meaning of colors across both modes.
  • Test thoroughly: Test your design in both light and dark modes.

Common Tips

  • Start with backgrounds: Define background colors first, then text colors.
  • Use gray scales: Maintain consistent gray shades across the design.
  • Keep accent colors consistent: Brand colors usually stay the same in both modes.
  • Test with actual users: Get feedback from users who prefer dark mode.
  • Animate transitions: Use transitions to smoothly switch between themes.