How to Add Dark Mode Support to WHMCS Themes

Dark mode has become an expected feature for modern web applications. Users appreciate reduced eye strain, better battery life on OLED screens, and personal preference options. This guide covers implementing dark mode in WHMCS themes from scratch.

Dark Mode Implementation Approaches

1. CSS Custom Properties (Recommended)

Use CSS variables to define colors that change based on mode:

• Define color variables in :root
• Override in dark mode selector
• Apply variables throughout stylesheet

2. Separate Stylesheets

Load different CSS files based on mode:

• Easier to maintain separately
• Requires page reload or dynamic loading
• Larger total CSS footprint

3. CSS Class Toggle

Add class to body element to switch modes:

• Works well with CSS variables
• JavaScript controls the toggle
• Can combine with system preference

Setting Up CSS Variables

Define Light Mode Colors

Start by defining your color palette as CSS custom properties:

• --bg-primary: Main background color
• --bg-secondary: Card/section backgrounds
• --text-primary: Main text color
• --text-secondary: Muted text color
• --border-color: Border colors
• --accent-color: Brand/accent color

Color Palette Example

Detecting System Preference

CSS Media Query

Use prefers-color-scheme media query to detect OS setting:

• Automatic detection without JavaScript
• Respects user's system preference
• Updates automatically if system changes

JavaScript Detection

For more control, detect preference in JavaScript:

• Check window.matchMedia for color-scheme
• Add listener for preference changes
• Combine with user toggle preference

Adding User Toggle

Toggle Button Design

Create an accessible toggle switch:

• Sun/moon icons for visual indication
• Place in header for easy access
• Include tooltip for clarity
• Smooth transition animation

Toggle Placement Options

• Header: Always visible, easy access
• Footer: Less prominent
• Settings page: With other preferences
• Dropdown menu: Saves header space

State Persistence

Save user preference for future visits:

• localStorage for client-side storage
• Cookie if server-side detection needed
• Check saved preference on page load
• Fall back to system preference if none saved

WHMCS Theme Implementation

File Modifications

Files to modify in your WHMCS theme:

• header.tpl: Add toggle button
• custom.css: Add dark mode styles
• custom.js: Toggle functionality

Adding to Header

Add toggle button to header navigation:

1. Edit header.tpl in your theme
2. Add toggle button HTML
3. Include appropriate icons
4. Style to match theme

CSS Structure

Organize your dark mode CSS:

• Define variables at top of stylesheet
• Group dark mode overrides together
• Use data-theme attribute on html/body
• Apply variables throughout existing styles

Component-Specific Styling

Navigation

• Dark background with light text
• Adjust dropdown backgrounds
• Update hover states
• Ensure logo visibility

Cards and Panels

• Slightly lighter than background
• Subtle border or shadow
• Consistent spacing

Forms and Inputs

• Dark input backgrounds
• Light text and placeholders
• Visible focus states
• Proper contrast for labels

Tables

• Alternate row colors for readability
• Header distinction
• Border visibility

Buttons

• Primary buttons may stay same color
• Secondary buttons need adjustment
• Outline buttons need border contrast
• Disabled states visible

Handling Third-Party Elements

Payment Gateway Widgets

• Some may not support dark mode
• Consider wrapper with light background
• Check gateway documentation

CAPTCHA

• reCAPTCHA has dark theme option
• Configure in WHMCS settings
• Pass theme parameter via API

Embedded Content

• iframes may have fixed colors
• Third-party widgets may clash
• Test thoroughly

Accessibility Considerations

Contrast Requirements

• WCAG AA: 4.5:1 for normal text
• WCAG AA: 3:1 for large text
• WCAG AAA: 7:1 for enhanced
• Test with contrast checking tools

Focus Indicators

• Must be visible in both modes
• Don't rely only on color
• Test keyboard navigation

Color Blindness

• Don't rely solely on color for meaning
• Test with color blindness simulators
• Ensure sufficient luminance contrast

Testing Dark Mode

Testing Checklist

Pages to Test

• Client area home
• My services list
• Service details
• Invoice view
• Support tickets
• Order forms
• Checkout
• Profile/settings

Browser Testing

• Chrome (Windows, Mac)
• Firefox
• Safari
• Edge
• Mobile browsers

Performance Considerations

Avoiding Flash of Wrong Mode

Prevent brief flash of light mode on dark preference:

• Load preference script in head
• Set data-theme before render
• Use CSS to hide until ready

CSS Size

• CSS variables add minimal overhead
• Avoid duplicating entire stylesheets
• Minify production CSS

Maintenance Tips

When Adding New Features

• Always use CSS variables for colors
• Test both modes immediately
• Add to dark mode overrides if needed

WHMCS Updates

• Check for new elements after updates
• Review changelog for UI changes
• Test dark mode after each update

Conclusion

Dark mode support significantly improves user experience and shows attention to modern design standards. Using CSS custom properties makes implementation maintainable, and proper testing ensures accessibility for all users. Implement dark mode to delight your customers and reduce eye strain for those working late.