PetalComponents.ColorSchemeSwitch (petal_components v4.11.2)

Copy Markdown View Source

Light / dark / system colour-scheme switching, in three faces.

<.color_scheme_switch id="scheme" variant="toggle" />
<.color_scheme_switch id="scheme" variant="dropdown" />
<.color_scheme_switch id="scheme" variant="segmented" />
  • toggle - a compact icon button that flips between light and dark instantly (the sun rotates out, the moon rotates in). No system option on purpose: a cycling three-state toggle can't show you which state you're in.
  • dropdown - the same compact trigger opening Light / Dark / System.
  • segmented - a three-way pill with all states visible. Settings pages, roomy navbars, preview chrome.

The scheme contract

Render <.color_scheme_script /> once in your root layout's <head>, before your app's JS. It applies the scheme before first paint (no flash), and defines window.PetalColorScheme:

  • preference - "light" | "dark" | "system". Stored in localStorage.scheme only for explicit choices; system is the absence of a stored value (drop-in compatible with existing petal apps that store scheme).

  • resolved - what the page is actually showing. While the preference is system, a matchMedia listener follows the OS live.
  • Changing scheme in one tab updates every open tab (a storage listener), and every change dispatches a window petal:scheme-changed event with {preference, resolved} - all switch instances stay in sync, and your own code can react too.

The switches require the PetalColorScheme hook from the JS bundle (hooks: { ...PetalComponents }).

Summary

Functions

color_scheme_script(assigns)

The no-flash scheme script. Render once in <head>, before app.js.

color_scheme_switch(assigns)

Renders a colour-scheme switch bound to the PetalColorScheme hook.

Functions

color_scheme_script(assigns)

The no-flash scheme script. Render once in <head>, before app.js.

color_scheme_switch(assigns)

Renders a colour-scheme switch bound to the PetalColorScheme hook.

The default icons are Heroicons (sun / moon / computer-desktop) to match the rest of the library. To use icons from another set, pass them in via the light_icon / dark_icon / system_icon slots - the slot content replaces the default and inherits the sizing and (for the toggle) the rotate transition.

Attributes

  • id (:string) (required)
  • variant (:string) - toggle flips light/dark; dropdown and segmented offer system too. Defaults to "toggle". Must be one of "toggle", "dropdown", or "segmented".
  • light_label (:string) - label/aria text (i18n). Defaults to "Light".
  • dark_label (:string) - label/aria text (i18n). Defaults to "Dark".
  • system_label (:string) - label/aria text (i18n). Defaults to "System".
  • labels (:boolean) - dropdown variant only: show text labels beside the icons instead of the icon-only rail. Defaults to false.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.

Slots

  • light_icon - replaces the sun icon - drop in any svg, it is sized to fill.
  • dark_icon - replaces the moon icon - drop in any svg, it is sized to fill.
  • system_icon - replaces the monitor icon - drop in any svg, it is sized to fill.