Hierarchical Data Passing
Relevant source files
The following files were used as context for generating this wiki page:
Hierarchical data passing in wouter-vue is a specialized mechanism designed to transmit reactive data down the routing tree. This system allows parent routing components to provide context or metadata that is automatically merged and made available to nested routes and their associated components.
The feature leverages Vue 3's reactivity system to ensure that data passed from a top-level router or a parent route remains synchronized as it flows through the component hierarchy. This is particularly useful for passing layout configurations, theme settings, or versioning information across different branches of an application's routing structure.
Sources: README.md:38, README.md:52, examples/example/src/pages/AboutPage.vue:15-28
Core Mechanisms for Data Transmission
The library provides two primary ways to interact with hierarchical data: through component props and through the Composition API via specialized composables.
Data Merging and Reactivity
As data flows down the routing tree, wouter-vue performs automatic merging of data objects. This ensures that a nested route can inherit data from its parent while also defining its own specific attributes.
The diagram above illustrates the flow of data where multiple levels of the routing tree contribute to the final state consumed by the end component.
Sources: README.md:38, examples/example/src/pages/AboutPage.vue:26-28
The useRouteData Composable
The useRouteData hook is the primary interface for accessing the merged data within a setup script. It returns a reactive reference to the current accumulated data for that specific branch of the route tree.
| Method | Description |
|---|---|
useRouteData() | Returns a reactive object containing all merged data from parent routes. |
props.data | Contains route-specific data passed directly via the :component prop on a <Route>. |
Sources: examples/example/src/pages/AboutPage.vue:64-74, README.md:52
Implementation in Nested Routing
Hierarchical data passing is intrinsically linked to the nesting capabilities of the router. When a <Route> component is defined with the nest prop, it creates a new routing context that preserves and extends the data from its predecessor.
Parameter and Data Propagation
In nested structures, parameters (like :id or :slug) and custom data objects are propagated from parents to children. This allows a deep child route to be aware of the context provided by its ancestors.
The sequence diagram shows how context is maintained across segments of a URL like /users/123/profile.
Sources: test/nested-route.test.ts:114-131, examples/example/src/pages/AboutPage.vue:64-70
Relative Navigation within Contexts
When data and routing are nested, the system supports relative link resolution using the ~ prefix. This allows components to navigate relative to the root while maintaining the data context of the current hierarchy.
| Navigation Type | Syntax | Result |
|---|---|---|
| Absolute | /home | Navigates to the root path regardless of current nesting. |
| Relative (Nested) | ~/home | Navigates to /home while bypassing the current nested base path. |
Sources: test/nested-route.test.ts:93-107
Practical Usage Examples
Developers typically use this feature to manage page metadata and UI states that depend on the route's position in the hierarchy.
Accessing Data in Components
The following snippet demonstrates how a component consumes both props-passed data and data retrieved from the hierarchical state.
// From examples/example/src/pages/AboutPage.vue
import { useRouteData } from 'wouter-vue';
const props = defineProps({
data: { type: Object, default: () => ({}) }
});
const routeData = useRouteData(); // Accesses the merged hierarchical data
Sources: examples/example/src/pages/AboutPage.vue:64-74
Data Fields Summary
Based on project examples, common data fields passed through this hierarchy include:
| Field | Purpose | Source Component |
|---|---|---|
theme | UI styling context (e.g., 'dark', 'light'). | Parent Route / Switch |
layout | Determines which layout wrapper to use. | Parent Route |
pageName | Display name for breadcrumbs or headers. | Individual Route |
version | Application or API versioning context. | Root Router |
Sources: examples/example/src/pages/AboutPage.vue:15-25
Conclusion
Hierarchical Data Passing in wouter-vue provides a robust, reactive bridge between the structure of the routing tree and the components that render within it. By automating the merging of data and parameters, it simplifies the management of complex, nested UI states while maintaining a minimal footprint consistent with the library's philosophy.