Function leptos_use::use_color_mode

source ·

pub fn use_color_mode() -> UseColorModeReturn

Expand description

Reactive color mode (dark / light / customs) with auto data persistence.

§Demo

Link to Demo

§Usage

let UseColorModeReturn {
    mode, // Signal<ColorMode::dark | ColorMode::light>
    set_mode,
    ..
} = use_color_mode();

By default, it will match with users’ browser preference using crate::use_preferred_dark (a.k.a. ColorMode::Auto). When reading the signal, it will by default return the current color mode (ColorMode::Dark, ColorMode::Light or your custom modes ColorMode::Custom("some-custom")). The ColorMode::Auto variant can be included in the returned modes by enabling the emit_auto option and using use_color_mode_with_options. When writing to the signal (set_mode), it will trigger DOM updates and persist the color mode to local storage (or your custom storage). You can pass ColorMode::Auto to set back to auto mode.

mode.get(); // ColorMode::Dark or ColorMode::Light

set_mode.set(ColorMode::Dark); // change to dark mode and persist

set_mode.set(ColorMode::Auto); // change to auto mode

§Options

let UseColorModeReturn { mode, set_mode, .. } = use_color_mode_with_options(
    UseColorModeOptions::default()
        .attribute("theme") // instead of writing to `class`
        .custom_modes(vec![
            // custom colors in addition to light/dark
            "dim".to_string(),
            "cafe".to_string(),
        ]),
); // Signal<ColorMode::Dark | ColorMode::Light | ColorMode::Custom("dim") | ColorMode::Custom("cafe")>

To persist color mode in a cookie, use use_cookie_with_options and specify .cookie_enabled(true).

Note: To work with SSR you have to add the axum or actix feature as described in crate::use_cookie.

let UseColorModeReturn { mode, set_mode, .. } = use_color_mode_with_options(
    UseColorModeOptions::default()
        .cookie_enabled(true),
);

// This adds the color mode class to the `<html>` element even with SSR
view! {
    <Html class=move || mode.get().to_string()/>
}

For a working example please check out the ssr example.

§Server-Side Rendering

On the server this will try to read the Sec-CH-Prefers-Color-Scheme header to determine the color mode. If the header is not present it will return ColorMode::Light. Please have a look at the linked documentation above for that header to see browser support as well as potential server requirements.

If you’re using axum you have to enable the "axum" feature in your Cargo.toml. In case it’s actix-web enable the feature "actix", for spin enable "spin".

§Bring your own header

In case you’re neither using Axum, Actix nor Spin, or the default implementation is not to your liking, you can provide your own way of reading the color scheme header value using the option crate::UseColorModeOptions::ssr_color_header_getter.

If cookie_enabled is set to true, a cookie will be used and if present this value will be used on the server as well as on the client. Please note that you have to add the axum or actix feature as described in crate::use_cookie.

Function leptos_use::use_color_modeCopy item path