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.

Release Status

• Current crate version: 0.1.0-alpha.4.
• Release wave: June 8, 2026 workspace integration update.
• Publish status: Prepared as a crates.io update for this package.
• Scope: Dioxus components and native metadata for no-reload theme switching.
• The README install examples and local workspace dependency requirements are aligned with this publish wave.

Install

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

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.

Integration Recipes

The component prelude includes the core integration helpers for route manifests, asset-budget categories, and migration planning:

use dioxus_theme::prelude::*;

let config = theme_cfg().with_default_theme("dark");
let policy = theme_route_policy().route("/settings");
let manifest = theme_component_manifest(&config, &policy);
let plan = theme_workertown_offload_plan(&config, &policy);

assert_eq!(manifest.package, "dioxus-theme");
assert!(plan.tasks.iter().any(|task| task == "serialize-token-css"));

Prefer the package-prefixed theme_* helper names for integration code. Component aliases such as Theme, Toggle, Select, AnimSelect, and SpeedSlider are intended for RSX-facing code.

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