a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
desertthunder.dev
hypermedia
frontend
signals
1---
2outline: deep
3---
4
5# Navigate Plugin
6
7The navigate plugin upgrades plain links and forms with client-side navigation, History API integration, and optional
8View Transition animations. It keeps your DOM-driven pages feeling app-like without giving up regular hyperlinks.
9
10## Quick Start
11
12```html
13<!-- Link-based navigation -->
14<a href="/about" data-volt-navigate>About</a>
15
16<!-- Form submissions (GET only) -->
17<form action="/search" method="get" data-volt-navigate>
18 <input name="q" placeholder="Search..." />
19 <button type="submit">Go</button>
20</form>
21```
22
23`data-volt-navigate` applies to `<a>` and `<form>` elements. Links use their `href`; forms default to `action` (or the current pathname) and serialize inputs into the query string for GET submissions.
24
25## Modifiers
26
27Attach modifiers with dot notation or suffixed attribute names (`data-volt-navigate-replace`).
28
29- `replace` - call `history.replaceState` instead of `pushState`; good for redirects or idempotent flows.
30- `prefetch` - issue a `<link rel="prefetch">` when the element is hovered or focused to warm the cache.
31- `notransition` - skip View Transition API usage, falling back to an immediate DOM swap.
32
33```html
34<a href="/settings" data-volt-navigate-notransition>Settings</a>
35<a href="/pricing" data-volt-navigate-prefetch>Pricing</a>
36<a href="/welcome" data-volt-navigate-replace>Skip intro</a>
37```
38
39## View Transitions
40
41By default the plugin wraps navigations in `startViewTransition` using the `"page-transition"` name. Use the
42`notransition` modifier to disable it per element, or switch names when navigating imperatively:
43
44```ts
45import { navigate } from "volt/plugins/navigate";
46
47await navigate("/projects/42", { transitionName: "project-detail" });
48```
49
50## Programmatic APIs
51
52Import helpers straight from `lib/src/plugins/navigate.ts` (re-exported by the runtime build):
53
54```ts
55import { goBack, goForward, initNavigationListener, navigate, redirect } from "volt/plugins/navigate";
56
57await navigate("/projects/123", { replace: false, transitionName: "detail" });
58redirect("/login"); // always uses replace
59goBack();
60goForward();
61
62// Restore scroll on history navigation
63const stop = initNavigationListener();
64// Later: stop();
65```
66
67`initNavigationListener` should run once during boot to restore scroll positions when users hit the back/forward
68buttons. It also emits a `volt:popstate` event mirroring the browser’s `popstate`.
69
70## Events
71
72Every navigation dispatches:
73
74- `volt:navigate` after the History API call, with `{ url, replace }` in `event.detail`.
75- `volt:popstate` from the history listener, with `{ state }` in `event.detail`.
76
77Use these to re-fetch data, invalidate caches, or sync routing signals for plugins such as `url`.
78
79## Handling External Links
80
81Navigation only intercepts same-origin URLs and primary-button clicks without modifier keys.
82External links, middle clicks, and `target="_blank"` continue to behave like normal browser navigation, preserving accessibility expectations.