	Language
	English
	English
	English
	French
	German
	German
	German
	Italian
	Korean
	Spanish
	Catalan
	Dutch
	Portuguese
	Portuguese
	Arabic
	Arabic
	Bulgarian
	Bangla
	Bosnian
	Czech
	Greek
	Estonian
	Persian
	Finnish
	Danish
	Hindi
	Indonesian
	Icelandic
	Croatian
	Japanese
	Hungarian
	Hebrew
	Georgian
	Central Kurdish
	Khmer
	Kyrgyz
	Kazakh
	Lithuanian
	Latvian
	Malay
	Norwegian
	Polish
	Romanian
	Russian
	Slovak
	Slovenian
	Serbian
	Serbian
	Swedish
	Thai
	Turkish
	Ukrainian
	Uzbek
	Vietnamese
	Chinese
	Chinese

LightSwitch

The PrimeFaces 17 themes support light and dark mode, selected by the CSS color-scheme of the page. LightSwitch sets the color-scheme to light or dark, automatically based on the OS settings or with its JavaScript API, and can remember the selection on the server.

LightSwitch Tag Documentation

LightSwitch switches the color scheme of the page between light and dark, automatically based on OS settings.

Name	Type	Required	Default	Description
id	String	false	generated	Unique identifier of the component in a namingContainer.
rendered	boolean	false	true	Boolean value to specify the rendering of the component, when set to false component will not be rendered.
binding	UIComponent	false	generated	An EL expression referring to a server side UIComponent instance in a backing bean.
widgetVar	String	false	generated ('widget_' + componentClientId)	Name of the client side widget.
automatic	boolean	false	true	Whether to automatically switch the color scheme based on OS settings.
dark	String	false		Optional theme name (e.g. 'metal') to switch to in dark mode. When not set, only the color scheme changes.
light	String	false		Optional theme name (e.g. 'aura') to switch to in light mode. When not set, only the color scheme changes.
selected	String	true		The currently selected color scheme: 'light' or 'dark'.

Name	Description
No records found.

Name	Type	Default	Description
switch	SelectEvent	true	Fires when the color scheme is switched.

Name	Library	Target
jquery/jquery.js	primefaces
core.js	primefaces
primefaces-extensions.js	primefaces-extensions
lightswitch/lightswitch.js	primefaces-extensions

RESOURCES

Tag Documentation Widget Source

JavaScript API

The widget methods light(), dark(), toggle() and automatic() switch the whole site. Open the theme configurator: its color scheme buttons follow the switch. automatic="false" keeps the switch from applying the OS setting on page load, so the stored choice wins.

Setup

Put LightSwitch in your template like:

<html style="color-scheme: \#{empty userBean.colorScheme ? 'light dark' : userBean.colorScheme}">
...
<pe:lightSwitch selected="\#{userBean.colorScheme}"/>

userBean should be a session scoped bean with a String type colorScheme property (with both getter and setter). Its value is light or dark. Rendering it on the html element avoids a flash of the other mode on page load.

This showcase does not bind selected: the theme configurator (palette button at the right edge) keeps the color scheme in the localStorage of the browser and applies it before the first paint, so the choice of the configurator and of the demo below always agree and survive a reload.

A different theme per mode

Optionally, the light and dark attributes name a theme to switch to as well, e.g. <pe:lightSwitch selected="\#{userBean.colorScheme}" light="aura" dark="metal"/>. Then also bind the theme in your web.xml:

<context-param>
    <param-name>primefaces.THEME</param-name>
    <param-value>\#{userBean.theme}</param-value>
</context-param>

Migration from PrimeFaces Extensions 16: selected holds the color scheme (light / dark) instead of a theme name, the light / dark attributes have no default anymore (formerly saga-blue / arya-blue), and the switch event carries the color scheme.

See also the PrimeFaces theming documentation.

OmniFaces `CombinedResourceHandler`

When a theme is switched with combined resources, we cannot find the theme link in the DOM tree. Therefore we need to add a node for the new theme. Important: this node will be added as the last element in the body.

Usage


<div class="card">
    <h5>JavaScript API</h5>
    <p>The widget methods <code>light()</code>, <code>dark()</code>, <code>toggle()</code> and <code>automatic()</code> switch
        the whole site. Open the theme configurator: its color scheme buttons follow the switch. <code>automatic="false"</code> keeps the switch from applying the OS setting on page load, so the stored choice wins.</p>
    <h:form id="formJsAPI">
        <pe:lightSwitch id="lightSwitch" widgetVar="lightSwitch" automatic="false"/>

        <p><p:toggleSwitch widgetVar="schemeToggle"
                           onchange="PF('lightSwitch').changeColorScheme(PF('schemeToggle').input.prop('checked') ? 'dark' : 'light')"/></p>

        <p><p:button value="Dark" onclick="PF('lightSwitch').dark();return false"/></p>

        <p><p:button value="Light" onclick="PF('lightSwitch').light();return false"/></p>

        <p><p:button value="Automatic (OS setting)" onclick="PF('lightSwitch').automatic();return false"/></p>
    </h:form>
    <script type="text/javascript">
        // keeps the toggle in sync when the scheme is changed by the buttons or by the theme configurator
        $(function () {
            var root = document.documentElement;
            function sync() {
                var toggle = PF('schemeToggle');
                if (!toggle) {
                    return;
                }
                var scheme = root.style.colorScheme;
                var dark = scheme ? scheme === 'dark' : window.matchMedia('(prefers-color-scheme: dark)').matches;
                if (toggle.input.prop('checked') !== dark) {
                    dark ? toggle.check() : toggle.uncheck();
                }
            }
            new MutationObserver(sync).observe(root, {attributes: true, attributeFilter: ['style']});
            setTimeout(sync, 0);
        });
    </script>
</div>