dioxus-theme 0.1.0-alpha.4

# 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

```toml
[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

```rust
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:

```rust
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.

```rust
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];
```

```css
[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:

```rust
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](https://github.com/Collin-Budrick/dioxus_template/blob/main/LICENSE-MIT))
- Apache License, Version 2.0 ([LICENSE-APACHE](https://github.com/Collin-Budrick/dioxus_template/blob/main/LICENSE-APACHE))

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