dioxus-theme-core

Serializable custom theme configuration for no-reload Dioxus 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-core = "0.1.0-alpha.1"

What It Provides

Theme registries with overrideable defaults.
Serializable theme tokens for SSR and lazy runtimes.
Animation, storage, target, and reduced-motion policy configuration.
Built-in animation presets: fade, cross-fade, slide, radial-wipe, and masked-wave.
Validation for route-safe selectors, storage keys, registered defaults, and CSS token values.
Token-name constants such as THEME_TOKEN_BG, THEME_TOKEN_FG, and THEME_TOKEN_ACCENT.
Visual-token manifest metadata for Shader, HoverFX, TextFX, and other packages listening to dioxus-theme:change.

Example

use dioxus_theme_core::{
    ThemeAnimationPreset, ThemeConfig, ThemeDefinition, ThemeRegistry, THEME_TOKEN_ACCENT,
};

let brand = ThemeDefinition::new("brand", "Brand")
    .with_token(THEME_TOKEN_ACCENT, "#0f766e");

let config = ThemeConfig::default()
    .with_registry(ThemeRegistry::default().with_theme(brand))
    .with_default_theme("brand")
    .with_animation_preset(ThemeAnimationPreset::MaskedWave)
    .with_animation_speed(125)
    .with_animation_storage_key("app-theme-animation")
    .with_animation_speed_storage_key("app-theme-animation-speed");

let report = config.validate();
assert!(report.is_valid());

Animation Timing

ThemeAnimationMode controls capability and fallback behavior:

ViewTransition: use the View Transition API when available.
CssOnly: use CSS variable transitions only.
None: apply changes immediately.

ThemeAnimationPreset controls the visual preset independently, and animation_speed is a percentage from 25 to 300. The default easing is ease-in-out; call with_easing("linear") or another easing string to override it.

Theme View Transitions isolate route-level view-transition-name elements by default so package theme switches animate the root snapshot without reordering named route content. Call with_view_transition_name_isolation(false) only when child named View Transition elements should participate in theme switches.

Visual Tokens

Theme semantic tokens are also exported as a shared visual contract:

use dioxus_theme_core::{
    theme_visual_token_manifest, THEME_CHANGE_EVENT, THEME_TOKEN_ACCENT, THEME_TOKEN_SURFACE,
    THEME_TOKEN_TEXT,
};

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 runtime dispatches dioxus-theme:change with raw tokens, semantic visualTokens, visualTokenCssVars, and visualTokenManifestVersion. Shader palettes, HoverFX sand/texture effects, and TextFX gradients can update from accent, muted, surface, and text without reloading or re-reading broad DOM state.

ViewTX Interop

Enable the optional viewtx feature to copy timing and reduced-motion policy from dioxus-viewtx-core:

dioxus-theme-core = { version = "0.1.0-alpha.1", features = ["viewtx"] }

let theme_config = ThemeConfig::default().with_viewtx_timing(&viewtx_config);

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-core 0.1.0-alpha.3