Themes and rendering preferences

Read explicit theme preferences without assuming a complete component rendering engine.

Configuration#

import type { ZeruxConfig } from 'zeruxjs';
export default {
  theme: { default: 'system', cookieName: 'theme', scriptPosition: 'head' }
} satisfies ZeruxConfig;

ThemeMode is light, dark or system. The runtime can process returned HTML and insert configured preference behavior. This is distinct from composing React/Vue components or generating a complete design system.

Server and browser reads#

zeruxjs/theme exports getThemeConfig, getThemeMode, getThemeByPrefersColor, getResolvedTheme, getThemeLabel and getThemeIcon. Server resolution can inspect request cookies and the prefers-color client hint; browser resolution can use matchMedia. Without client information, server output cannot know every user's device preference.

Preference changes#

setTheme updates the browser document and preference cookie; it does nothing when no document exists. Treat a theme cookie as a display preference only, never identity or permission. Ensure your CSS supports the emitted classes and color-scheme behavior.

Accessible controls#

Label the control, keep keyboard focus visible and respect reduced motion. Test first paint and preference changes. If you render different client/server markup based on a theme, account for hydration consistency in the chosen renderer.

Documentation site policy#

This static site uses CSS system preference plus an optional browser-local theme override. It does not execute the framework runtime at request time, and does not claim its static theme control installs the framework theme system.