dioxus-theme

Dioxus components and native metadata for no-reload theme switching.

This crate is part of the Dioxus SSR package workspace. The APIs are pre-1.0 and may change between releases while the package family stabilizes.

Install

[dependencies]
dioxus-theme = "0.1.0-alpha.1"

What It Provides

ThemeProvider, ThemeToggle, ThemeSelect, ThemeAnimationSelect, and ThemeAnimationSpeedSlider components.
use_theme storage hook backed by the native-port storage adapter.
Native package action metadata for theme, animation preset, and animation speed controls.
Re-exports for core config, animation presets, validation types, built-in token constants, and visual-token manifest helpers.

Controls

use dioxus::prelude::*;
use dioxus_theme::{
    ThemeAnimationPreset, ThemeAnimationSelect, ThemeAnimationSpeedSlider, ThemeConfig,
    ThemeProvider, ThemeSelect, ThemeToggle,
};

#[component]
fn Settings() -> Element {
    let config = ThemeConfig::default()
        .with_animation_preset(ThemeAnimationPreset::MaskedWave)
        .with_animation_speed(100);

    rsx! {
        ThemeProvider { config: config.clone(),
            ThemeToggle { class: "theme-button" }
            ThemeSelect { config: config.clone(), class: "theme-select" }
            ThemeAnimationSelect { config: config.clone(), class: "theme-select" }
            ThemeAnimationSpeedSlider { config, class: "theme-slider" }
        }
    }
}

The controls render SSR-safe HTML using data-dxr-on-* resumability attributes. They include stable ids, accessible labels, aria-live current labels, and slider output text. The default handler ids are:

theme.toggle
theme.set
theme.cycle
theme.animation
theme.animation-speed

Visual Token Interop

dioxus-theme re-exports the semantic token contract used by visual packages:

use dioxus_theme::{theme_visual_token_manifest, THEME_CHANGE_EVENT, THEME_TOKEN_ACCENT};

let manifest = theme_visual_token_manifest();
assert_eq!(THEME_CHANGE_EVENT, "dioxus-theme:change");
assert!(manifest.tokens.iter().any(|token| token.css_var == THEME_TOKEN_ACCENT));

The browser runtime includes tokens, visualTokens, and visualTokenCssVars in every dioxus-theme:change event, so Shader palettes, HoverFX sand/texture colors, and TextFX gradient colors can react to theme changes without page reload.

use dioxus_theme::{THEME_TOKEN_ACCENT, THEME_TOKEN_MUTED, THEME_TOKEN_SURFACE, THEME_TOKEN_TEXT};

let shader_palette = [THEME_TOKEN_ACCENT, THEME_TOKEN_SURFACE, THEME_TOKEN_MUTED];
let hoverfx_sand = [THEME_TOKEN_SURFACE, THEME_TOKEN_ACCENT];
let textfx_gradient = [THEME_TOKEN_ACCENT, THEME_TOKEN_TEXT, THEME_TOKEN_MUTED];

[data-dxh-effect="sand"] {
  --dxh-sand-color: var(--dxt-panel);
  --dxh-sand-highlight: var(--dxt-accent);
}

.dxt-effect-gradient-shift {
  --dxt-gradient-a: var(--dxt-accent);
  --dxt-gradient-b: var(--dxt-fg);
  --dxt-gradient-c: var(--dxt-muted);
}

Native Metadata

Use theme_native_package_actions(route) to advertise native-port actions for non-web shells. theme_native_action returns the configured storage keys, active animation preset, animation speed, and fallback mode so native hosts can mirror the same controls.

Workspace package dependencies:

dioxus-native-port
dioxus-theme-core

Feature Flags

default: web
desktop: dioxus/desktop
native: dioxus/native, dioxus-native-port/native
server: dioxus/server
viewtx: forwards the optional dioxus-theme-core/viewtx interop feature
web: dioxus/web, dioxus-native-port/web

License

Licensed under either of:

MIT license (LICENSE-MIT)
Apache License, Version 2.0 (LICENSE-APACHE)

Repository: https://github.com/Collin-Budrick/dioxus_template

dioxus-theme 0.1.0-alpha.2