APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Theme Switcher

Persistent CSS themes with optional Bootstrap 5.3 color-mode integration.

The shared CoreApp\Personalization\ThemeSwitcher provides theme selection, cookie persistence, stylesheet registration and document-level theme metadata. Applications configure their own themes through APPNETOS class extensions.

How it works

During __invoke(), the switcher initializes its theme definitions and reads the selected key from the APPNETOS Cookie controller. If the cookie is missing or refers to an unavailable theme, the first valid theme is selected and stored. If no valid themes exist, the switcher renders nothing.

The selected theme's src is registered through Core CSS. Core UI receives data-appnetos-theme and, when configured, data-bs-theme for the root <html> element. The shared JavaScript and CSS resources for the selector interface are registered during normal rendering.

The HTML root attributes and stylesheet must be collected after the switcher has initialized. AJAX theme selection persists the new choice; applying the change to the already loaded page requires client-side handling or a reload.

Theme configuration

Override getThemes() in an application-specific class extension. Each entry requires a unique nonempty key and a nonempty CSS src. Titles, icons and Bootstrap color modes are optional.

protected function getThemes(): array
{
    return [
        [
            'key' => 'light',
            'title' => 'Light',
            'src' => '/src/my-app/app/css/light.min.css',
            'icon' => '/src/my-app/app/img/themes/light.svg',
            'bootstrap_theme' => 'light',
        ],
        [
            'key' => 'dark',
            'title' => 'Dark',
            'src' => '/src/my-app/app/css/dark.min.css',
            'icon' => '/src/my-app/app/img/themes/dark.svg',
            'bootstrap_theme' => 'dark',
        ],
    ];
}
Field Purpose
key Required unique identifier used for persistence and the APPNETOS theme attribute.
src Required public stylesheet path registered through Core CSS.
title Optional display label; defaults to the theme key.
icon Optional icon path for the selector UI.
bootstrap_theme Optional value for data-bs-theme on the HTML root.

Persistent cookies and switcher identifiers

Override getThemeSwitcherId() to assign a stable identifier. The switcher uses it to generate a logical cookie key; the shared Cookie controller adds the active application or session scope and normalizes the physical browser cookie name.

protected function getThemeSwitcherId(): string
{
    return 'theme-switcher-docs';
}

protected function getThemeCookieLifetime(): int
{
    return 31536000; // 365 days
}

Cookies are configured by the shared controller with the root path, automatic HTTPS detection, HttpOnly enabled and SameSite=Lax. The default Theme Switcher lifetime is 365 days and can be overridden as shown above.

Different identifiers retain independent selections; pages using the same identifier share the corresponding selection within the applicable cookie scope. Use only one Theme Switcher per page, because the stylesheet and HTML theme attributes are document-wide.

Core UI and stylesheet output

For an active dark theme with Bootstrap integration, the rendered document can include:

<html lang="en" data-appnetos-theme="dark" data-bs-theme="dark">

The active theme stylesheet is registered through Core\Css::add() with the priority returned by getThemeCssPriority() (1000 by default). The application's rendering pipeline is responsible for emitting the registered CSS resources.

The Bootstrap color-mode attribute is optional. If a theme omits bootstrap_theme, the switcher does not set data-bs-theme for that theme.

AJAX and customization

loadThemes() renders the configured choices and their active state. The selectTheme() endpoint validates the supplied switcher identifier and theme key, then writes the selected key to its persistent cookie. Invalid selections are rejected.

Applications can customize getThemes(), getThemeSwitcherId(), getThemeCookieLifetime(), getThemeCssPriority(), resolveThemeTitle() and the Bootstrap-versioned template paths. The shared implementation currently supports Bootstrap 5.3.8 templates.

Next Steps

Previous

Personalization

Explore Personalization

Next

Content

Explore Content