Skip to main content

Crate g3_route_transitions

Crate g3_route_transitions 

Source
Expand description

Route-owned View Transition helpers for Dioxus Router.

Using the crate takes three pieces, and all three are needed before every transition is visible:

  1. Route metadata. #[derive(RouteTransitions)] on your Routable enum decides which NavigationTransition runs between two routes.
  2. Snapshot regions. Wrapper components mark which parts of the DOM move. A transition only animates the regions it knows about (see What moves).
  3. Animated navigation. animated_navigate, try_animated_back, and animated_back_or_navigate capture the old page before changing the route. Calling navigator().push(...) directly skips the animation.

§Quick start

use dioxus::prelude::*;
use g3_route_transitions::{
    RouteTransitionApp, RouteTransitionBaseRegion, RouteTransitionPageRegion, RouteTransitions,
    animated_back_or_navigate, animated_navigate,
};

#[derive(Clone, PartialEq, Routable, RouteTransitions)]
enum Route {
    #[transition(layer = stack_root)]
    #[route("/")]
    Home {},

    #[transition(layer = stack_page)]
    #[route("/details/:id")]
    Details { id: u32 },

    #[transition(layer = sheet)]
    #[route("/compose")]
    Compose {},
}

#[component]
fn App() -> Element {
    // The overlay region: the part that rises and falls for sheets.
    rsx! { RouteTransitionApp { Router::<Route> {} } }
}

// Ordinary (non-sheet) pages sit in a base region and wrap their content in
// a page region. The base region stays put and dims under a sheet; the page
// region slides for `Forward`/`Backward`.
#[component]
fn Home() -> Element {
    rsx! {
        RouteTransitionBaseRegion {
            RouteTransitionPageRegion {
                h1 { "Home" }
                button {
                    onclick: move |_| async move { animated_navigate(Route::Details { id: 1 }).await },
                    "Open details"
                }
                button {
                    onclick: move |_| async move { animated_navigate(Route::Compose {}).await },
                    "Compose"
                }
            }
        }
    }
}

#[component]
fn Details(id: u32) -> Element {
    rsx! {
        RouteTransitionBaseRegion {
            RouteTransitionPageRegion {
                button {
                    onclick: move |_| async move { animated_back_or_navigate(Route::Home {}).await },
                    "Back"
                }
                "Details {id}"
            }
        }
    }
}

// Sheets render *without* a base or page region, so the whole sheet is
// captured as part of the overlay.
#[component]
fn Compose() -> Element {
    rsx! {
        button {
            onclick: move |_| async move { animated_back_or_navigate(Route::Home {}).await },
            "Close"
        }
    }
}

fn main() {
    dioxus::launch(App);
}

With this setup:

NavigationTransition
Home → DetailsForward, and Back is Backward
Home or Details → ComposePresentSheet, and Back is DismissSheet
Details(1) → Details(2)CrossFade, since nothing relates two stack_page values

The RouteTransitions derive documents every option and the exact rule order.

§What moves

Each transition animates specific snapshot regions. Anything outside them is part of the root snapshot.

TransitionAnimated regionsEverything else
CrossFaderoot and RouteTransitionBaseRegion fade–
Forward / BackwardRouteTransitionPageRegion slides with platform motion; a RouteTransitionSegmentRegion outside any page slides as a full-width filmstriproot and base region switch instantly
PresentSheet / DismissSheetRouteTransitionOverlayRegion (added by RouteTransitionApp) rises or falls; the base region and page region underneath dim (and on iOS, scale)root is hidden
Instantnothing; the route changes without a View Transition–

In every transition, RouteTransitionPersistentRegion stays in place above all other snapshots, such as a desktop rail beside a rising sheet.

Consequences worth knowing:

  • RouteTransitionApp on its own only produces visible cross-fades. Forward/Backward need a RouteTransitionPageRegion or RouteTransitionSegmentRegion, and sheets need a base region to rise over.
  • A sheet route must not render a base region or page region. Those are captured separately from the overlay, so the sheet’s content would be missing from the rising image.
  • A segment inside a RouteTransitionPageRegion never moves by itself; the whole page moves instead. Use segments without a page wrapper for tabbed content that should slide under a fixed header.
  • Persistent chrome only stays still if both routes render it in the same place, sheet routes included. Otherwise it fades.
  • Each region may appear at most once in the document at a time. Duplicate view-transition-names make the browser skip the animation.

§Platform motion

Platform picks the visual style for the same semantic transition. Call set_platform at startup (and whenever the app’s mode changes); otherwise platform falls back to detect_platform.

Animations are skipped, and the route is changed directly, when the browser lacks document.startViewTransition or the user prefers reduced motion.

Re-exports§

pub use RouteTransitionBaseRegion_completions::Component::RouteTransitionBaseRegion;
pub use RouteTransitionOverlayRegion_completions::Component::RouteTransitionOverlayRegion;
pub use RouteTransitionSegmentRegion_completions::Component::RouteTransitionSegmentRegion;
pub use RouteTransitionPageRegion_completions::Component::RouteTransitionPageRegion;
pub use RouteTransitionPersistentRegion_completions::Component::RouteTransitionPersistentRegion;
pub use RouteTransitionPageFrame_completions::Component::RouteTransitionPageFrame;
pub use RouteTransitionStyles_completions::Component::RouteTransitionStyles;
pub use RouteTransitionApp_completions::Component::RouteTransitionApp;

Structs§

RouteTransitionAppProps
Properties for the RouteTransitionApp component.
RouteTransitionBaseRegionProps
Properties for the RouteTransitionBaseRegion component.
RouteTransitionOverlayRegionProps
Properties for the RouteTransitionOverlayRegion component.
RouteTransitionPageFrameProps
Properties for the RouteTransitionPageFrame component.
RouteTransitionPageRegionProps
Properties for the RouteTransitionPageRegion component.
RouteTransitionPersistentRegionProps
Properties for the RouteTransitionPersistentRegion component.
RouteTransitionSegmentRegionProps
Properties for the RouteTransitionSegmentRegion component.
RouteTransitionStylesProps
Properties for the RouteTransitionStyles component.

Enums§

NavigationTransition
A semantic navigation event chosen by RouteTransitions::transition_to or RouteTransitions::transition_back.
Platform
Platform styling mode for the transition stylesheet - mirrors the iOS-vs-Material split app component libraries (e.g. Ionic, g3-ui) already use for widget styling, so the same signal can drive both.
RouteTransitionLayer
The navigation role a route declares with #[transition(layer = ...)].

Constants§

ROUTE_TRANSITION_BASE_REGION_CLASS
Class applied by RouteTransitionBaseRegion.
ROUTE_TRANSITION_OVERLAY_REGION_CLASS
Class applied by RouteTransitionOverlayRegion and RouteTransitionApp.
ROUTE_TRANSITION_PAGE_FRAME_CLASS
Class for a shell around a RouteTransitionPageRegion that holds chrome a sheet should cover, such as a phone’s bottom tab bar.
ROUTE_TRANSITION_PAGE_REGION_CLASS
Class applied by RouteTransitionPageRegion.
ROUTE_TRANSITION_PERSISTENT_REGION_CLASS
Class applied by RouteTransitionPersistentRegion.
ROUTE_TRANSITION_SEGMENT_REGION_CLASS
Class applied by RouteTransitionSegmentRegion.

Statics§

ROUTE_TRANSITIONS_CSS
The stylesheet backing every transition. Link it once via RouteTransitionStyles (or RouteTransitionApp), or attach it yourself if the app manages its own document::Link tags.

Traits§

RouteTransitions
Decides which NavigationTransition runs between two routes and how history is written.

Functions§

RouteTransitionApp
The app-level wrapper: links the stylesheet and wraps its children in an overlay region (the part that rises and falls for sheets). Place Router::<Route> {} inside it.
RouteTransitionBaseRegion
Content that stays in place during navigation and dims underneath a presented sheet: typically an ordinary page’s shell, including a tab bar.
RouteTransitionOverlayRegion
Content that rises over the base region for PresentSheet and falls away for DismissSheet.
RouteTransitionPageFrame
A shell around a RouteTransitionPageRegion and the chrome a sheet should cover, such as a phone’s bottom tab bar.
RouteTransitionPageRegion
One routed page, captured as a single viewport-sized image for Forward and Backward (platform push/pop motion) and dimmed under sheets.
RouteTransitionPersistentRegion
Chrome that stays exactly where it is during every transition, such as a desktop navigation rail beside the page.
RouteTransitionSegmentRegion
Content that slides by itself for Forward and Backward, such as the body of a segmented control under a fixed header.
RouteTransitionStyles
Links ROUTE_TRANSITIONS_CSS and renders its children unchanged.
animated_back_or_navigate
Pop real router history like try_animated_back, or, when there is no previous entry (for example after a deep link), navigate to fallback with animated_navigate.
animated_navigate
Navigate to route with the transition chosen by current.transition_to(&route), pushing or replacing history according to current.replaces_history(&route).
animated_navigate_with
Navigate to route with animation instead of the one the route rules choose, still pushing or replacing history by current.replaces_history(&route).
detect_platform
Detect a reasonable default platform from cfg(target_os) (native mobile builds) or, on wasm, from the user agent.
platform
The platform currently used to style transitions. Falls back to compile-time/runtime auto-detection if set_platform was never called.
set_platform
Explicitly set the platform used to pick a transition’s visual style. Call this once at startup and again whenever the app’s platform mode changes (e.g. a user-facing iOS/Material style toggle).
try_animated_back
Pop real router history with current.transition_back().
use_browser_history_transitions
Animate the browser’s Back and Forward buttons (and history.back() from other code) with the same transitions as try_animated_back and animated_navigate.
use_route_transition_settled
False until the transition that brought this component in has finished, then true. Call it in the page, or in a list on it.

Derive Macros§

RouteTransitions
Derives route-owned View Transition behavior for a Dioxus Routable enum.