Appearance¶

System color-scheme tracking with an optional app-level override. The screen host publishes the platform's light/dark setting into this module; use_color_scheme and use_theme subscribe to it and re-render components when the effective scheme changes.

import pythonnative as pn


@pn.component
def SchemeAwareBadge():
    scheme = pn.use_color_scheme()  # "light" or "dark"
    theme = pn.use_theme()  # built-in theme for the scheme
    return pn.Text(
        f"Currently {scheme}",
        style={"color": theme["text_color"]},
    )

Force an appearance regardless of the system setting (for example from an in-app toggle), or return to following the system:

pn.appearance.set_color_scheme("dark")  # force dark
pn.appearance.set_color_scheme(None)  # follow the system again

System color-scheme (light / dark mode) tracking.

The platform screen host publishes the operating system's current appearance here (Android: Configuration.uiMode; iOS: UITraitCollection.userInterfaceStyle), and components read it back through use_color_scheme or use_theme, both of which re-render when the scheme changes.

Apps can also override the scheme (e.g. an in-app appearance setting) with set_color_scheme; the override wins over the system value until cleared with None.

Example

from pythonnative import appearance appearance.get_color_scheme() 'light' appearance.set_color_scheme("dark") # app-level override appearance.get_color_scheme() 'dark' appearance.set_color_scheme(None) # follow the system again

Functions:

Name	Description
`subscribe`	Register `callback` to fire whenever the effective scheme changes.
`set_system_color_scheme`	Publish the operating system's current scheme.
`set_color_scheme`	Set (or clear) the app-level scheme override.
`get_color_scheme`	Return the effective scheme: the app override if set, else the system value.
`get_system_color_scheme`	Return the system-reported scheme, ignoring any app override.
`reset_color_scheme`	Reset to system `"light"` with no override. Intended for tests.

Attributes:

Name	Type	Description
`ColorScheme`		The two supported appearance values.

ColorScheme `module-attribute` ¶

ColorScheme = Literal['light', 'dark']

The two supported appearance values.

subscribe ¶

subscribe(callback: Callable[[], None]) -> Callable[[], None]

Register callback to fire whenever the effective scheme changes.

Returns an unsubscribe function. Threadsafe.

set_system_color_scheme ¶

set_system_color_scheme(scheme: str) -> None

Publish the operating system's current scheme.

Called by the platform screen host on create/resume and whenever the system reports an appearance change. Invalid values are ignored. Subscribers are only notified when the effective scheme (after any app override) actually changes.

set_color_scheme ¶

set_color_scheme(scheme: Optional[str]) -> None

Set (or clear) the app-level scheme override.

Parameters:

Name	Type	Description	Default
`scheme`	`Optional[str]`	`"light"` or `"dark"` to force that appearance regardless of the system setting, or `None` to follow the system again.	required

get_color_scheme ¶

get_color_scheme() -> str

Return the effective scheme: the app override if set, else the system value.

get_system_color_scheme ¶

get_system_color_scheme() -> str

Return the system-reported scheme, ignoring any app override.

reset_color_scheme ¶

reset_color_scheme() -> None

Reset to system "light" with no override. Intended for tests.

Next steps¶

Theming with use_theme and ThemeContext: see Style and the Styling guide.