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:
- Route metadata.
#[derive(RouteTransitions)]on yourRoutableenum decides whichNavigationTransitionruns between two routes. - Snapshot regions. Wrapper components mark which parts of the DOM move. A transition only animates the regions it knows about (see What moves).
- Animated navigation.
animated_navigate,try_animated_back, andanimated_back_or_navigatecapture the old page before changing the route. Callingnavigator().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:
| Navigation | Transition |
|---|---|
| Home → Details | Forward, and Back is Backward |
| Home or Details → Compose | PresentSheet, 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.
| Transition | Animated regions | Everything else |
|---|---|---|
CrossFade | root and RouteTransitionBaseRegion fade | – |
Forward / Backward | RouteTransitionPageRegion slides with platform motion; a RouteTransitionSegmentRegion outside any page slides as a full-width filmstrip | root and base region switch instantly |
PresentSheet / DismissSheet | RouteTransitionOverlayRegion (added by RouteTransitionApp) rises or falls; the base region and page region underneath dim (and on iOS, scale) | root is hidden |
Instant | nothing; 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:
RouteTransitionAppon its own only produces visible cross-fades.Forward/Backwardneed aRouteTransitionPageRegionorRouteTransitionSegmentRegion, 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
RouteTransitionPageRegionnever 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§
- Route
Transition AppProps - Properties for the
RouteTransitionAppcomponent. - Route
Transition Base Region Props - Properties for the
RouteTransitionBaseRegioncomponent. - Route
Transition Overlay Region Props - Properties for the
RouteTransitionOverlayRegioncomponent. - Route
Transition Page Frame Props - Properties for the
RouteTransitionPageFramecomponent. - Route
Transition Page Region Props - Properties for the
RouteTransitionPageRegioncomponent. - Route
Transition Persistent Region Props - Properties for the
RouteTransitionPersistentRegioncomponent. - Route
Transition Segment Region Props - Properties for the
RouteTransitionSegmentRegioncomponent. - Route
Transition Styles Props - Properties for the
RouteTransitionStylescomponent.
Enums§
- Navigation
Transition - A semantic navigation event chosen by
RouteTransitions::transition_toorRouteTransitions::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.
- Route
Transition Layer - 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
RouteTransitionOverlayRegionandRouteTransitionApp. - ROUTE_
TRANSITION_ PAGE_ FRAME_ CLASS - Class for a shell around a
RouteTransitionPageRegionthat 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(orRouteTransitionApp), or attach it yourself if the app manages its owndocument::Linktags.
Traits§
- Route
Transitions - Decides which
NavigationTransitionruns between two routes and how history is written.
Functions§
- Route
Transition App - 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. - Route
Transition Base Region - Content that stays in place during navigation and dims underneath a presented sheet: typically an ordinary page’s shell, including a tab bar.
- Route
Transition Overlay Region - Content that rises over the base region for
PresentSheetand falls away forDismissSheet. - Route
Transition Page Frame - A shell around a
RouteTransitionPageRegionand the chrome a sheet should cover, such as a phone’s bottom tab bar. - Route
Transition Page Region - One routed page, captured as a single viewport-sized image for
ForwardandBackward(platform push/pop motion) and dimmed under sheets. - Route
Transition Persistent Region - Chrome that stays exactly where it is during every transition, such as a desktop navigation rail beside the page.
- Route
Transition Segment Region - Content that slides by itself for
ForwardandBackward, such as the body of a segmented control under a fixed header. - Route
Transition Styles - Links
ROUTE_TRANSITIONS_CSSand 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 tofallbackwithanimated_navigate. - animated_
navigate - Navigate to
routewith the transition chosen bycurrent.transition_to(&route), pushing or replacing history according tocurrent.replaces_history(&route). - animated_
navigate_ with - Navigate to
routewithanimationinstead of the one the route rules choose, still pushing or replacing history bycurrent.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_platformwas 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 astry_animated_backandanimated_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§
- Route
Transitions - Derives route-owned View Transition behavior for a Dioxus
Routableenum.