use-url-hash

Track the URL fragment as a typed value decoded by parse.


Package	`@vizejs/composable/use-url-hash`
Own the source	`vize lib pull composable:use-url-hash`
Runtime exports	`useUrlHash`
Gzip budget	2560 B

Usage

import { useUrlHash } from "@vizejs/composable/use-url-hash";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useUrlHash`	state	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

API

`useUrlHash`

Track the URL fragment as a typed value decoded by parse.

function useUrlHash<Value>(options: UseTypedUrlHashOptions<Value>): UrlHashControls<Value>

`useUrlHash`

Track the URL fragment as a plain string (without the leading #).

function useUrlHash(options?: UseUrlHashOptions): UrlHashControls<string>

`useUrlHash`

Synchronize a typed value with the URL fragment (location.hash). Reading follows hashchange and popstate. Writing state updates the fragment through history.replaceState (or pushState with mode: "push"), which neither scrolls to an anchor nor fires hashchange; an empty serialized value removes the fragment. Values are percent-decoded on read and minimally encoded on write. Server rendering: browsers never send the fragment, so without a host the value is ssrHash (when given) or the default, and no global is read. Inside a component the browser hash is first read after mounting (initialRead defaults to "post-flush" there), so hydration never mismatches. Listeners are removed with the owning reactive scope.

function useUrlHash<Value>( options: UseUrlHashOptions | UseTypedUrlHashOptions<Value> = {}, ): UrlHashControls<Value> | UrlHashControls<string>

const { state: tab } = useUrlHash({
  parse: (raw) => (raw === "settings" ? "settings" : "profile"),
  serialize: (value) => value,
  default: "profile" as "profile" | "settings",
});

Types

`UrlHashHost`

Minimal window surface used by useUrlHash.

Member	Type	Description
`location`	`{ /** Fragment including the leading #, or "". / readonly hash: string; /* Path component. / readonly pathname: string; /* Query component including the leading ?, or "". */ readonly search: string; }`	Current location; only the URL parts are read.
`history`	`{ /** Current history entry state, preserved when replacing. / readonly state: unknown; /* Replace the current entry's URL. / readonly replaceState: (data: unknown, unused: string, url: string) => void; /* Push a new entry with the given URL. */ readonly pushState: (data: unknown, unused: string, url: string) => void; }`	Session history used to write the fragment without scrolling.

`UseUrlHashOptions`

Options shared by both useUrlHash overloads.

Member	Type	Description
`host`?	`MaybeRefOrGetter<UrlHashHost \| null \| undefined>`	Browser host. `null`/`undefined` keeps the default (server rendering).
`mode`?	`UrlHistoryMode`	History write mode for changes made through `state`.
`ssrHash`?	`MaybeRefOrGetter<string \| undefined>`	Raw hash (without `#`) to use while no host is attached. Browsers never send the fragment to servers, so pass it only when it is known (for example from a client-side redirect).
`initialRead`?	`"sync" \| "post-flush"`	When the browser hash is first read. `"post-flush"` keeps the server value through hydration and reads the real hash after mounting.

`UseTypedUrlHashOptions`

Options for a typed useUrlHash with an explicit codec.

Member	Type	Description
`host`?	`MaybeRefOrGetter<UrlHashHost \| null \| undefined>`	Browser host. `null`/`undefined` keeps the default (server rendering).
`mode`?	`UrlHistoryMode`	History write mode for changes made through `state`.
`ssrHash`?	`MaybeRefOrGetter<string \| undefined>`	Raw hash (without `#`) to use while no host is attached. Browsers never send the fragment to servers, so pass it only when it is known (for example from a client-side redirect).
`initialRead`?	`"sync" \| "post-flush"`	When the browser hash is first read. `"post-flush"` keeps the server value through hydration and reads the real hash after mounting.
`parse`	`(raw: string) => Value`	Decode the raw (percent-decoded, `#`-less) hash. Throwing selects `default`.
`serialize`	`(value: Value) => string`	Encode a value to a raw hash. An empty string removes the fragment.
`default`	`Value`	Value used for an empty or unparsable hash.

`UrlHashControls`

Reactive state and controls returned by useUrlHash.

Member	Type	Description
`state`	`Ref<Value>`	Writable hash value; assignments update the URL.
`supported`	`Readonly<Ref<boolean>>`	Whether a browser host is attached.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent parse failure, cleared by the next successful read.
`refresh`	`() => void`	Re-read the current location hash.