Skip to main content

Instant Theme Switching

How LibreApps Desktop enables real-time theme changes without rebuilds.

Overview​

One of LibreApps Desktop's most powerful features is the ability to switch themes instantly in the browser. This is achieved through a combination of class-based CSS variables and a centralized theme configuration.

How it Works​

1. Class-Based CSS Variables​

Instead of just defining variables in :root, LibreApps Desktop also defines them within specific theme classes in src/app/gallery-themes.css:

.theme-candy {
  --primary: oklch(65% 0.2 30);
  /* ... */
}

.theme-default {
  --primary: oklch(60% 0.15 250);
  /* ... */
}

2. Dynamic Class Toggling​

The Theme Gallery and the Theme Customizer use React state to toggle these classes on the <body> or <html> element. When a class like theme-default is added, its CSS variables take precedence over the default :root variables, instantly updating the entire UI.

3. Persistence​

The selected theme is typically stored in localStorage or a cookie, ensuring that the user's preference is maintained across page reloads.

Benefits​

  • Designer Friendly: Designers can see their changes immediately without waiting for a build.
  • User Personalization: Allow your end-users to choose their preferred color scheme.
  • A/B Testing: Easily test different brand identities with real users.

Best Practices​

  • ✅ Do this: Ensure all your custom themes are included in the gallery-themes.css file if you want them to be switchable at runtime.
  • ✅ Do this: Use the useTheme hook to access and update the current theme programmatically.
  • ❌ Don't do this: Use inline styles for brand colors; they bypass the class-based switching mechanism.