useBrowserLocation Hook
Relevant source files
The following files were used as context for generating this wiki page:
The useBrowserLocation hook is a core utility in wouter-vue designed to provide a reactive interface to the browser's current URL path. It follows the project's minimalist philosophy by leveraging Vue 3's Composition API to track and update the window.location.pathname without requiring a complex global state management system.
This hook is the default mechanism for routing in wouter-vue when no custom base path or alternative location hook (such as memory or hash-based) is provided. It ensures that components stay in sync with the browser's navigation history, specifically reacting to pushState and replaceState events.
Sources: README.md:16-25, src/use-browser-location.ts:1-10
Architecture and Reactive Flow
The hook operates by returning a tuple containing a reactive reference to the current path and a navigation function. It monitors the browser's history state to ensure that any back/forward navigation or programmatic history changes trigger a component update.
Data Synchronization Flow
The following diagram illustrates how the hook synchronizes the browser's history state with the Vue component reactivity system.
This flow ensures that whether a user clicks the back button or the application calls a navigation function, the application state remains consistent.
Sources: test/use-browser-location.test.ts:32-48, src/use-browser-location.ts:15-30
Key API Components
The useBrowserLocation hook provides two primary capabilities: reading the current location and modifying it.
Function Signature
The hook returns an array with two elements:
location: A VueRef<string>representing the currentpathname.navigate: A function to update the current location.
| Element | Type | Description |
|---|---|---|
location | Ref<string> | The current window pathname (e.g., /about). |
navigate | (to: string, options?: object) => void | A function to change the URL using history API. |
Sources: src/use-browser-location.ts:10-15, test/use-browser-location.test.ts:12-25
Programmatic Navigation
Programmatic navigation can be performed using the second returned value. This function supports both push (default) and replace transitions by interacting with the history.pushState and history.replaceState methods.
const [location, navigate] = useBrowserLocation();
// Navigate to a new route
navigate('/users/123');
// Replace the current history entry
navigate('/login', { replace: true });
Sources: test/use-browser-location.test.ts:51-71, examples/example/src/pages/AboutPage.vue:85-95
Path Normalization and Validation
Internal utilities ensure that paths handled by the hook are consistent across the application. This includes stripping query parameters and hashes for link active state detection, and resolving target paths between href and to properties.
Helper Functions
| Function | Source File | Description |
|---|---|---|
normalizePath | path-helpers.ts | Removes query strings and hashes; handles trailing slashes. |
resolveTargetPath | path-helpers.ts | Determines the final URL from various prop inputs. |
validateTargetPathProps | path-helpers.ts | Logs warnings if navigation props are missing or redundant. |
Sources: src/helpers/path-helpers.ts:12-45, types/helpers.d.ts:7-12
Path Resolution Logic
When a navigation event is triggered (e.g., through a Link component or direct hook call), the library processes the input path to ensure it matches the expected internal format.
Sources: src/helpers/path-helpers.ts:12-29
Integration with Search Parameters
While useBrowserLocation focuses on the path, the project also provides useSearch and useSearchParams to handle the query string portion of the URL. In the AboutPage.vue example, these are used together to construct a full path representation.
// Example of combining location and search params
const [location] = useLocation(); // Internally uses useBrowserLocation
const [searchParams] = useSearchParams();
const fullPath = computed(() => {
let path = location.value || '';
const searchStr = searchParams.value?.toString();
return searchStr ? `${path}?${searchStr}` : path;
});
Sources: examples/example/src/pages/AboutPage.vue:90-117, test/use-browser-location.test.ts:74-85
Usage Summary
The useBrowserLocation hook serves as the foundational reactive link between a Vue 3 application and the browser's URL. By wrapping the standard History API in Vue's reactivity system, it allows developers to build high-performance routing components that respond instantly to URL changes without the overhead of heavier routing libraries.