useHashLocation Hook

Relevant source files

The following files were used as context for generating this wiki page:

• src/use-hash-location.ts
• package.json
• README.md
• src/helpers/path-helpers.ts
• types/helpers.d.ts

The useHashLocation hook is a specialized routing utility in the wouter-vue library designed to manage application state based on the URL hash (fragment identifier). It serves as an alternative to the standard browser history API, enabling routing in environments where the server is not configured to handle single-page application (SPA) fallback routes or where hash-based navigation is preferred.

This hook leverages Vue 3's Composition API to provide a reactive interface for reading and updating the current hash-based path. It ensures that components remain in sync with the browser's hashchange events while providing a programmatic navigation interface similar to useLocation.

Sources: package.json:56, README.md:16-25, types/helpers.d.ts:13

Core Architecture and Logic

The useHashLocation hook operates by intercepting and parsing the window.location.hash property. It treats the portion of the URL following the # symbol as the primary routing path.

Path Resolution and Normalization

When the hook initializes, it retrieves the current hash. If no hash is present, it defaults to the root path /. The logic involves stripping the leading # character to treat the remainder as a standard path string. This path is often further processed by normalizePath to ensure consistency (e.g., removing trailing slashes or handling empty strings).

Sources: src/helpers/path-helpers.ts:12-28, src/use-hash-location.ts

Event Synchronization

The hook maintains reactivity by listening to global browser events. Specifically, it attaches a listener to the hashchange event. Whenever the user navigates via the browser's back/forward buttons or manually edits the URL hash, the hook updates its internal reactive state, triggering re-renders in dependent Vue components.

API Interface

The hook returns a tuple-like array containing the current location and a function to update that location.

Element	Type	Description
location	Ref<string>	A reactive reference to the current path (excluding the # prefix).
navigate	(to: string, options?: object) => void	A function to programmatically update the hash.

The Navigate Function

The navigation function provided by the hook updates the window.location.hash. In hash-based routing, this typically results in a new entry in the browser's history stack, unless specific options are provided to replace the current entry.

Sources: src/use-hash-location.ts, examples/example/README.md:92-97

Integration with Helpers

The hook relies on several utility functions to maintain robust routing behavior. These helpers are shared across different location strategies (browser, hash, and memory).

Path Normalization

The normalizePath utility is critical for ensuring that paths like #/about/ and #/about are treated identically by the router logic.

export function normalizePath(path: string): string {
  if (!path) return '/'
  let normalized = path.split('?')[0]
  normalized = normalized.split('#')[0]
  if (normalized === '') return '/'
  if (normalized !== '/' && normalized.endsWith('/')) {
    normalized = normalized.slice(0, -1)
  }
  return normalized
}

Sources: src/helpers/path-helpers.ts:12-25

Navigation Guards

Before performing navigation, the system often checks for modifier keys (Ctrl, Meta, Alt, Shift) using shouldIgnoreNavigationClick. This ensures that standard browser behaviors (like opening a link in a new tab) are not overridden by the hash navigation logic.

Sources: src/helpers/path-helpers.ts:77-79

Usage Comparison

While the library defaults to standard path-based routing, useHashLocation is explicitly exported for cases where hash routing is mandatory.

Conclusion

The useHashLocation hook provides a lightweight, reactive bridge between the browser's URL hash and the Vue 3 Composition API. By abstracting the hashchange event and window.location.hash manipulation into a simple [location, navigate] interface, it allows developers to implement stable routing in environments where traditional path-based navigation is not feasible. Its reliance on shared path helpers ensures consistency with the broader wouter-vue ecosystem.