See how the auto theme feature works. Select a theme mode and observe how it resolves to an actual theme based on your OS preference.

Preview

The auto theme feature provides a 3-way toggle for theme selection: Light, Dark, and Auto. When set to "Auto", the application automatically follows the operating system's color scheme preference using the CSS media query prefers-color-scheme.

• Three theme modes - Light, Dark, and Auto (System)
• Real-time updates - Theme changes instantly when OS preference changes
• Persistent setting - Theme mode saved to localStorage
• No FOUC - Flash of unstyled content prevented with isInline script
• SSR compatible - Graceful fallback on server-side rendering

Theme Mode Values

The theme type in config.ts now includes the 'auto' option.

Settings Panel

The SettingsPanel component provides a dropdown with all three theme mode options.

1. Resolving Auto Mode

When the theme mode is 'auto', we use the browser's matchMedia API to detect the OS preference.

2. Real-time OS Theme Detection

A MediaQueryList listener is set up to detect when the user changes their OS theme preference.

3. Applying the Theme

The resolved theme is applied by adding the appropriate CSS class to the body element.

4. FOUC Prevention

To prevent a flash of unstyled content on page load, an isInline script in app.html resolves and applies the theme before the page renders.

The theme mode setting is persisted in localStorage under the key theme-mode.

The auto theme feature is built into the SettingsPanel component. Simply include the component in your layout and users can select their preferred theme mode.

To test the auto theme feature, you can change your OS theme preference or use browser DevTools.

Here's how the auto theme system processes theme changes:

User selects "Auto" in SettingsPanel
         ↓
localStorage['theme-mode'] = 'auto'
         ↓
getResolvedThemeMode('auto') checks prefers-color-scheme
         ↓
Returns 'light' or 'dark' based on OS
         ↓
Applies pa-mode-light or pa-mode-dark to body
         ↓
MediaQueryList listener watches for OS changes
         ↓
On change → reapply resolved theme

Server-Side Rendering (SSR)

On the server, window.matchMedia is not available. The implementation defaults to 'light' on the server, and the client-side hydration corrects it if needed.

FOUC Prevention

The isInline script in app.html runs synchronously before the page renders, ensuring the correct theme class is applied immediately. This prevents any flash of the wrong theme.

Listener Cleanup

The MediaQueryList listener is properly cleaned up when:

• The user switches away from "Auto" mode
• The SettingsPanel component is destroyed

The prefers-color-scheme media query is supported in all modern browsers: