+
{brand} · {category}
diff --git a/packages/magazin/routes/products/[slug].tsx b/packages/magazin/routes/products/[slug].tsx
index c7d9bcc3..5d08d167 100644
--- a/packages/magazin/routes/products/[slug].tsx
+++ b/packages/magazin/routes/products/[slug].tsx
@@ -28,12 +28,16 @@ export function ProductPage({ slug }: { slug: string }) {
-
+
= (
to: Path,
- options?: { replace?: boolean; state?: S }
+ options?: { replace?: boolean; state?: S; transition?: boolean }
) => void;
type HookReturnValue = { hook: BaseLocationHook; navigate: Navigate };
diff --git a/packages/wouter-preact/types/router.d.ts b/packages/wouter-preact/types/router.d.ts
index 8133e53b..56a0872e 100644
--- a/packages/wouter-preact/types/router.d.ts
+++ b/packages/wouter-preact/types/router.d.ts
@@ -11,6 +11,21 @@ export type Parser = (
loose?: boolean
) => { pattern: RegExp; keys: string[] };
+// Standard navigation options supported by all built-in location hooks
+export type NavigateOptions = {
+ replace?: boolean;
+ state?: S;
+ /** Enable view transitions for this navigation (used with aroundNav) */
+ transition?: boolean;
+};
+
+// Function that wraps navigate calls, useful for view transitions
+export type AroundNavHandler = (
+ navigate: (to: Path, options?: NavigateOptions) => void,
+ to: Path,
+ options?: NavigateOptions
+) => void;
+
// the object returned from `useRouter`
export interface RouterObject {
readonly hook: BaseLocationHook;
@@ -20,9 +35,19 @@ export interface RouterObject {
readonly parser: Parser;
readonly ssrPath?: Path;
readonly ssrSearch?: SearchString;
+ readonly ssrContext?: SsrContext;
readonly hrefs: HrefsFormatter;
+ readonly aroundNav: AroundNavHandler;
}
+// state captured during SSR render
+export type SsrContext = {
+ // if a redirect was encountered, this will be populated with the path
+ redirectTo?: Path;
+ // HTTP status code to set for SSR response
+ statusCode?: number;
+};
+
// basic options to construct a router
export type RouterOptions = {
hook?: BaseLocationHook;
@@ -31,5 +56,7 @@ export type RouterOptions = {
parser?: Parser;
ssrPath?: Path;
ssrSearch?: SearchString;
+ ssrContext?: SsrContext;
hrefs?: HrefsFormatter;
+ aroundNav?: AroundNavHandler;
};
diff --git a/packages/wouter-preact/types/use-browser-location.d.ts b/packages/wouter-preact/types/use-browser-location.d.ts
index 6485d76e..5b23c2e2 100644
--- a/packages/wouter-preact/types/use-browser-location.d.ts
+++ b/packages/wouter-preact/types/use-browser-location.d.ts
@@ -18,7 +18,7 @@ export const useHistoryState: () => T;
export const navigate: (
to: string | URL,
- options?: { replace?: boolean; state?: S }
+ options?: { replace?: boolean; state?: S; transition?: boolean }
) => void;
/*
diff --git a/packages/wouter-preact/types/use-hash-location.d.ts b/packages/wouter-preact/types/use-hash-location.d.ts
index 3e649f5c..0fb32d3f 100644
--- a/packages/wouter-preact/types/use-hash-location.d.ts
+++ b/packages/wouter-preact/types/use-hash-location.d.ts
@@ -2,7 +2,7 @@ import { Path } from "./location-hook.js";
export function navigate(
to: Path,
- options?: { state?: S; replace?: boolean }
+ options?: { state?: S; replace?: boolean; transition?: boolean }
): void;
export function useHashLocation(options?: {
diff --git a/packages/wouter/src/index.js b/packages/wouter/src/index.js
index 07e6288e..957a7be6 100644
--- a/packages/wouter/src/index.js
+++ b/packages/wouter/src/index.js
@@ -40,6 +40,8 @@ const defaultRouter = {
ssrContext: undefined,
// customizes how `href` props are transformed for
hrefs: (x) => x,
+ // wraps navigate calls, useful for view transitions
+ aroundNav: (n, t, o) => n(t, o),
};
const RouterCtx = createContext(defaultRouter);
@@ -71,7 +73,9 @@ const useLocationFromRouter = (router) => {
// (This is achieved via `useEvent`.)
return [
relativePath(router.base, location),
- useEvent((to, navOpts) => navigate(absolutePath(to, router.base), navOpts)),
+ useEvent((to, opts) =>
+ router.aroundNav(navigate, absolutePath(to, router.base), opts)
+ ),
];
};
@@ -270,6 +274,7 @@ export const Link = forwardRef((props, ref) => {
/* eslint-disable no-unused-vars */
replace /* ignore nav props */,
state /* ignore nav props */,
+ transition /* ignore nav props */,
/* eslint-enable no-unused-vars */
...restProps
diff --git a/packages/wouter/test/router.test.tsx b/packages/wouter/test/router.test.tsx
index b1abe151..6314c626 100644
--- a/packages/wouter/test/router.test.tsx
+++ b/packages/wouter/test/router.test.tsx
@@ -211,6 +211,49 @@ describe("`hrefs` prop", () => {
});
});
+describe("`aroundNav` prop", () => {
+ it("sets the router's `aroundNav` property", () => {
+ const aroundNav = () => {};
+
+ const { result } = renderHook(() => useRouter(), {
+ wrapper: (props) => (
+ {props.children}
+ ),
+ });
+
+ expect(result.current.aroundNav).toBe(aroundNav);
+ });
+
+ it("is inherited from parent router", () => {
+ const aroundNav = () => {};
+
+ const { result } = renderHook(() => useRouter(), {
+ wrapper: (props) => (
+
+ {props.children}
+
+ ),
+ });
+
+ expect(result.current.aroundNav).toBe(aroundNav);
+ });
+
+ it("can be overridden in nested router", () => {
+ const parentAroundNav = () => {};
+ const childAroundNav = () => {};
+
+ const { result } = renderHook(() => useRouter(), {
+ wrapper: (props) => (
+
+ {props.children}
+
+ ),
+ });
+
+ expect(result.current.aroundNav).toBe(childAroundNav);
+ });
+});
+
it("updates the context when settings are changed", () => {
const state: { renders: number } & Partial> = {
renders: 0,
diff --git a/packages/wouter/test/view-transitions.test.tsx b/packages/wouter/test/view-transitions.test.tsx
new file mode 100644
index 00000000..6c44c8bd
--- /dev/null
+++ b/packages/wouter/test/view-transitions.test.tsx
@@ -0,0 +1,106 @@
+import { test, expect, describe, mock, afterEach } from "bun:test";
+import { render, cleanup, fireEvent } from "@testing-library/react";
+import { Router, Link, useLocation, type AroundNavHandler } from "../src/index.js";
+import { memoryLocation } from "../src/memory-location.js";
+
+afterEach(cleanup);
+
+describe("view transitions", () => {
+ test("Link with transition prop triggers aroundNav with transition in options", () => {
+ // 1. Setup: create aroundNav callback that captures calls
+ const aroundNav: AroundNavHandler = mock((navigate, to, options) => {
+ navigate(to, options);
+ });
+
+ const { hook } = memoryLocation({ path: "/" });
+
+ // 2. Render Link with transition prop
+ const { getByTestId } = render(
+
+
+ About
+
+
+ );
+
+ // 3. Click the link
+ fireEvent.click(getByTestId("link"));
+
+ // 4. Verify aroundNav was called with transition: true in options
+ expect(aroundNav).toHaveBeenCalledTimes(1);
+
+ const [navigateFn, to, options] = (aroundNav as ReturnType)
+ .mock.calls[0];
+
+ expect(typeof navigateFn).toBe("function");
+ expect(to).toBe("/about");
+ expect(options.transition).toBe(true);
+ });
+
+ test("useLocation navigate with transition option triggers aroundNav", () => {
+ const aroundNav: AroundNavHandler = mock((navigate, to, options) => {
+ navigate(to, options);
+ });
+
+ const { hook } = memoryLocation({ path: "/" });
+
+ const NavigateButton = () => {
+ const [, navigate] = useLocation();
+ return (
+
+ );
+ };
+
+ const { getByTestId } = render(
+
+
+ );
+
+ fireEvent.click(getByTestId("btn"));
+
+ expect(aroundNav).toHaveBeenCalledTimes(1);
+
+ const [, to, options] = (aroundNav as ReturnType).mock.calls[0];
+ expect(to).toBe("/about");
+ expect(options.transition).toBe(true);
+ });
+
+ test("navigation does not happen if aroundNav doesn't call navigate", () => {
+ // aroundNav that does nothing
+ const aroundNav: AroundNavHandler = mock(() => {});
+
+ const { hook } = memoryLocation({ path: "/" });
+
+ const LocationDisplay = () => {
+ const [location] = useLocation();
+ return {location};
+ };
+
+ const { getByTestId } = render(
+
+
+ );
+
+ // Verify initial location
+ expect(getByTestId("location").textContent).toBe("/");
+
+ // Click the link
+ fireEvent.click(getByTestId("link"));
+
+ // aroundNav was called but didn't call navigate
+ expect(aroundNav).toHaveBeenCalledTimes(1);
+
+ // Location should remain unchanged
+ expect(getByTestId("location").textContent).toBe("/");
+ });
+});
diff --git a/packages/wouter/types/memory-location.d.ts b/packages/wouter/types/memory-location.d.ts
index d40d44a0..04888b41 100644
--- a/packages/wouter/types/memory-location.d.ts
+++ b/packages/wouter/types/memory-location.d.ts
@@ -7,7 +7,7 @@ import {
type Navigate = (
to: Path,
- options?: { replace?: boolean; state?: S }
+ options?: { replace?: boolean; state?: S; transition?: boolean }
) => void;
type HookReturnValue = {
diff --git a/packages/wouter/types/router.d.ts b/packages/wouter/types/router.d.ts
index 29ca142d..56a0872e 100644
--- a/packages/wouter/types/router.d.ts
+++ b/packages/wouter/types/router.d.ts
@@ -11,6 +11,21 @@ export type Parser = (
loose?: boolean
) => { pattern: RegExp; keys: string[] };
+// Standard navigation options supported by all built-in location hooks
+export type NavigateOptions = {
+ replace?: boolean;
+ state?: S;
+ /** Enable view transitions for this navigation (used with aroundNav) */
+ transition?: boolean;
+};
+
+// Function that wraps navigate calls, useful for view transitions
+export type AroundNavHandler = (
+ navigate: (to: Path, options?: NavigateOptions) => void,
+ to: Path,
+ options?: NavigateOptions
+) => void;
+
// the object returned from `useRouter`
export interface RouterObject {
readonly hook: BaseLocationHook;
@@ -20,13 +35,17 @@ export interface RouterObject {
readonly parser: Parser;
readonly ssrPath?: Path;
readonly ssrSearch?: SearchString;
+ readonly ssrContext?: SsrContext;
readonly hrefs: HrefsFormatter;
+ readonly aroundNav: AroundNavHandler;
}
// state captured during SSR render
export type SsrContext = {
// if a redirect was encountered, this will be populated with the path
redirectTo?: Path;
+ // HTTP status code to set for SSR response
+ statusCode?: number;
};
// basic options to construct a router
@@ -39,4 +58,5 @@ export type RouterOptions = {
ssrSearch?: SearchString;
ssrContext?: SsrContext;
hrefs?: HrefsFormatter;
+ aroundNav?: AroundNavHandler;
};
diff --git a/packages/wouter/types/use-browser-location.d.ts b/packages/wouter/types/use-browser-location.d.ts
index 6485d76e..5b23c2e2 100644
--- a/packages/wouter/types/use-browser-location.d.ts
+++ b/packages/wouter/types/use-browser-location.d.ts
@@ -18,7 +18,7 @@ export const useHistoryState: () => T;
export const navigate: (
to: string | URL,
- options?: { replace?: boolean; state?: S }
+ options?: { replace?: boolean; state?: S; transition?: boolean }
) => void;
/*
diff --git a/packages/wouter/types/use-hash-location.d.ts b/packages/wouter/types/use-hash-location.d.ts
index 3e649f5c..0fb32d3f 100644
--- a/packages/wouter/types/use-hash-location.d.ts
+++ b/packages/wouter/types/use-hash-location.d.ts
@@ -2,7 +2,7 @@ import { Path } from "./location-hook.js";
export function navigate(
to: Path,
- options?: { state?: S; replace?: boolean }
+ options?: { state?: S; replace?: boolean; transition?: boolean }
): void;
export function useHashLocation(options?: {
diff --git a/specs/view-transitions-spec.md b/specs/view-transitions-spec.md
new file mode 100644
index 00000000..63a938cb
--- /dev/null
+++ b/specs/view-transitions-spec.md
@@ -0,0 +1,124 @@
+# View Transitions API in Wouter
+
+View Transitions are baseline available (as of Oct 2025). This doc describes the API for using them in wouter.
+
+Though the browser API is super simple, there are certain obstacles to overcome:
+
+## Problems
+
+- `startViewTransition` accepts a callback that must modify the DOM synchronously
+- `setState` can't guarantee that the DOM will be modified synchronously
+- There is `flushSync` but it requires `react-dom`, we want wouter to only depend on `react`
+- Wouter uses `useSyncExternalStore` to react to events. In theory sending event inside `flushSync`
+ should trigger updates synchronously, but this is not 100% proven and could break
+
+## Solution
+
+Users implement their own behavior before and after navigate is called, so they can control
+view transitions behavior.
+
+### Basic Implementation (enable view transitions by default)
+
+```js
+import { flushSync } from "react-dom";
+
+function aroundNav(navigate, ...navArgs) {
+ // Feature detection for older browsers
+ if (!document.startViewTransition) {
+ navigate(...navArgs);
+ return;
+ }
+
+ document.startViewTransition(() => {
+ flushSync(() => {
+ navigate(...navArgs);
+ });
+ });
+}
+
+
+ ;
+```
+
+Alternatively, with explicit arguments:
+
+```js
+function aroundNav(navigate, to, options) {
+ if (!document.startViewTransition) {
+ navigate(to, options);
+ return;
+ }
+
+ document.startViewTransition(() => {
+ flushSync(() => {
+ navigate(to, options);
+ });
+ });
+}
+```
+
+### Granular control (opt-in transitions)
+
+For more control over when transitions occur:
+
+```jsx
+// In your component
+
+ Home
+;
+
+// Or programmatically
+const [location, navigate] = useLocation();
+navigate("/", { transition: true });
+```
+
+**Note:** The `transition` prop is now part of wouter's type definitions (`NavigateOptions`) and is available on all location hooks (`useBrowserLocation`, `useHashLocation`, `memoryLocation`). When `` calls `navigate(targetPath, props)`, all props are automatically passed as navigation options, making them available in `aroundNav`.
+
+```js
+import { flushSync } from "react-dom";
+
+function aroundNav(navigate, to, options) {
+ // Feature detection
+ if (!document.startViewTransition) {
+ navigate(to, options);
+ return;
+ }
+
+ // Only use transitions when explicitly requested
+ if (options?.transition) {
+ document.startViewTransition(() => {
+ flushSync(() => {
+ navigate(to, options);
+ });
+ });
+ } else {
+ navigate(to, options);
+ }
+}
+```
+
+### TypeScript types
+
+Wouter provides built-in types for view transitions:
+
+```typescript
+import type { NavigateOptions, AroundNavHandler } from "wouter";
+
+// NavigateOptions already includes transition
+const navigate = (to: string, options?: NavigateOptions) => {
+ // options.transition is available
+ // options.replace is available
+ // options.state is available
+};
+
+// AroundNavHandler type for the aroundNav callback
+const aroundNav: AroundNavHandler = (navigate, to, options) => {
+ if (options?.transition) {
+ // handle transition
+ }
+ navigate(to, options);
+};
+```
+
+The `transition` option is included in `NavigateOptions` along with `replace` and `state`, and is available on all built-in location hooks.