AnimatedSwitch Component
Relevant source files
The following files were used as context for generating this wiki page:
The AnimatedSwitch component is a specialized routing utility in the wouter-vue library designed to provide smooth, animated transitions between routes. It acts as a high-level wrapper around the standard Switch component, integrating Vue's native <Transition> system to handle entry and exit animations for matched route components.
Beyond animation, AnimatedSwitch plays a critical role in the library's hierarchical data passing system. It provides a reactive data context to its children, allowing developers to pass state or configuration objects down the routing tree. This is particularly useful for global layouts or theme settings that need to be accessible to all nested Route components.
Sources: src/components/AnimatedSwitch.tsx:1-5, README.md:46-47, examples/example/src/components/AppRoutes.vue:3-17
Core Architecture and Implementation
AnimatedSwitch is implemented using the Vue Composition API and functional h-render patterns. It leverages the useLocation hook to track the current path and uses that value as a unique key for the internal Switch component. This keying strategy forces the <Transition> component to trigger whenever the URL changes, even if the same layout component is being reused.
The following diagram illustrates how the AnimatedSwitch component structures the internal render tree and handles route changes:
The diagram shows the hierarchy where AnimatedSwitch provides data context before rendering the Transition and Switch components.
Sources: src/components/AnimatedSwitch.tsx:28-60
Key Properties and Configuration
The component accepts properties to control the animation behavior and the data passed to child routes.
| Property | Type | Default | Description |
|---|---|---|---|
name | string | 'fade' | The CSS class name for the Vue transition. |
mode | string | 'out-in' | The transition mode (e.g., 'out-in', 'in-out', 'default'). |
location | string | undefined | Optional manual override for the current path. |
data | Object | undefined | Reactive data object provided to child components. |
Sources: src/components/AnimatedSwitch.tsx:21-41
Hierarchical Data Passing
One of the primary features of AnimatedSwitch is its ability to inject data into the routing tree using the RouteDataKey. This is achieved through the provideVue function within the setup block. The data provided is reactive, meaning that updates to the object passed to the :data prop will automatically propagate to all descendant routes.
This sequence demonstrates how data flows from the top-level route configuration through the AnimatedSwitch to individual page components.
Sources: src/components/AnimatedSwitch.tsx:44-45, examples/example/src/pages/AboutPage.vue:74-75
Implementation Example
In a typical application setup, AnimatedSwitch is used to wrap multiple Route components.
// examples/example/src/components/AppRoutes.vue:31-35
const routeData = ref({
theme: 'dark',
layout: 'default',
version: '1.0.0',
});
// Template
<AnimatedSwitch name="fade" mode="out-in" :data="routeData">
<Route path="/" :component="HomePage" />
<Route path="/about" :component="AboutPage" />
</AnimatedSwitch>
Sources: examples/example/src/components/AppRoutes.vue:5-17, examples/example/src/components/AppRoutes.vue:31-35
Integration with Vue Transition
AnimatedSwitch wraps the Switch component within a Vue <Transition>. To ensure animations trigger correctly on every navigation event, the locationValue (derived from the useLocation hook) is applied as a key to the Switch.
// src/components/AnimatedSwitch.tsx:50-59
return () => {
const locationValue = (location as ComputedRef<Path>).value
return h(
Transition,
{
name: props.name || 'fade',
mode: props.mode || 'out-in',
},
() =>
h(
Switch,
{
key: locationValue,
location: props.location,
data: props.data,
},
slots
)
)
}
Sources: src/components/AnimatedSwitch.tsx:47-60
Path Normalization and Matching
While AnimatedSwitch handles the rendering of the transition, it relies on path-helpers to interpret the current location. Navigation clicks are filtered to ensure standard browser behavior (like opening links in new tabs via Ctrl+Click) is maintained without triggering the transition unnecessarily.
The normalizePath utility ensures that transitions are not falsely triggered by changes in query parameters or hashes unless the base path itself has changed.
Sources: src/helpers/path-helpers.ts:13-28, src/helpers/path-helpers.ts:77-79
Conclusion
The AnimatedSwitch component is a vital part of the wouter-vue ecosystem, providing both visual polish through Vue Transitions and architectural depth through hierarchical data injection. By keying transitions to the reactive location state, it ensures a consistent user experience during navigation across all defined routes.