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.

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: Serializable custom theme configuration for no-reload Dioxus theme switching.
The README install examples and local workspace dependency requirements are aligned with this publish wave.

Install

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

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.4", features = ["viewtx"] }

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

Integration Recipes

Theme integrations can emit route metadata and reuse it for SSR, Strata, asset-budget reports, WorkerTown offload planning, and optimizer caches:

use dioxus_theme_core::prelude::*;

let config = theme().with_default_theme("dark");
let policy = theme_route_policy()
    .route("/settings")
    .diagnostics(ThemeDiagnosticVerbosity::Summary)
    .fallback(ThemeFallbackStrategy::StoredOrSystem);

let manifest = theme_manifest_fragment(&config, &policy);
let batch = theme_serialize_batch([(&config, policy.clone())], ThemeBatchOptions::default())?;
let budget = theme_asset_budget_bridge(&config.output_report(&policy));
let migration = theme_strata_migration_plan(&config, &policy);

assert_eq!(manifest.package, "dioxus-theme");
assert!(batch.total_bytes > 0);
assert!(budget.categories.iter().any(|category| category.name == "style"));
assert!(migration.steps.iter().any(|step| step.contains("Strata")));
# Ok::<(), serde_json::Error>(())

ThemeRuntimeIds::duplicate_ids and deduped protect generated script/style ids, theme_precomputed_css_fragments exposes reusable custom-property CSS, and theme_optimizer_artifacts returns minifier/cache-friendly artifact hashes.

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.4