AbsoluteJS

Cross-Framework Navigation

A link from a React page to a Svelte page, or back, can navigate without a full page load. Call enableNavigation() on both pages and use plain links or the Link components.

#Overview

When you click a link to another page, AbsoluteJS fetches the target page's HTML and loads its stylesheets first. Then it tears down the current page, swaps the head and body, and hydrates the new page. The swap runs inside a View Transition where the browser supports one.

Back and forward work across the two pages and restore scroll positions. Island stores keep their values. The new page's title is announced to screen readers. Under secureHeaders(), the new page's scripts and styles run with the current page's nonce. If anything fails, the browser does a normal page load.

#Enable Navigation

Import enableNavigation from @absolutejs/absolute/client/navigation and call it on every page that takes part, in a React useEffect or a Svelte onMount. The first call installs it for the tab. Later calls do nothing, so every page can call it.

Don't call disableNavigation() when a component unmounts. The page unmounts on every navigation.

#React Page

Use Link from @absolutejs/absolute/react/components. It renders a plain <a>, prefetches the target, and needs no router. A click on a link to another page goes to the navigation layer.

TSX
// src/frontend/react/pages/Store.tsx
import { useEffect } from 'react';
import { enableNavigation } from '@absolutejs/absolute/client/navigation';
import { Link } from '@absolutejs/absolute/react/components';
import { useIslandStore } from '@absolutejs/absolute/react/hooks';
import { cartStore } from '../../../shared/cartStore';

export const Store = () => {
  const items = useIslandStore(cartStore, (state) => state.items);
  const addItem = useIslandStore(cartStore, (state) => state.addItem);

  useEffect(() => {
    enableNavigation();
  }, []);

  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <title>Store</title>
      </head>
      <body>
        <nav>
          <Link href="/checkout">Checkout</Link>
        </nav>
        <button onClick={addItem} type="button">
          Add to cart ({items})
        </button>
      </body>
    </html>
  );
};

Inside a <UniversalRouter>, a link that matches one of its routes still navigates through react-router. Other links go to the navigation layer.

#Svelte Page

Use Link from @absolutejs/absolute/svelte/router/Link.svelte. It takes to instead of href.

SVELTE
<!-- src/frontend/svelte/pages/Checkout.svelte -->
<script lang="ts">
  import { onMount } from 'svelte';
  import Link from '@absolutejs/absolute/svelte/router/Link.svelte';
  import { enableNavigation } from '@absolutejs/absolute/client/navigation';
  import { useIslandStore } from '@absolutejs/absolute/svelte';
  import { cartStore } from '../../../shared/cartStore';

  const items = useIslandStore(cartStore, (state) => state.items);

  onMount(() => {
    enableNavigation();
  });
</script>

<svelte:head>
  <title>Checkout</title>
</svelte:head>

<nav>
  <Link to="/store">Back to the store</Link>
</nav>
<p>Items in your cart: {$items}</p>

When a mounted <Router> has a route for the URL, the Svelte router handles the click. When no mounted router matches, the click goes to the navigation layer.

#Island Stores

Stores made with createIslandStore survive the swap. Import the same store on both pages. In the example, items added on the React page show on the Svelte page, and the count is still there when you go back.

TS
// src/shared/cartStore.ts
import { createIslandStore } from '@absolutejs/absolute/client';

export const cartStore = createIslandStore('cart', { items: 0 }, (set) => ({
  addItem: () => set((state) => ({ items: state.items + 1 }))
}));

#Prefetch

Both Link components take a prefetch mode and a prerender flag. A navigation uses the prefetched response when there is one.

PropBehavior
'viewport'Prefetch when the link scrolls into view, and on hover or pointer down. The production default.
'hover'Prefetch on hover only. The development default.
'none'No prefetch for this link.
prerenderAlso add a prerender speculation rule on hover or pointer down.
TSX
import { Link } from '@absolutejs/absolute/react/components';

export const StoreNav = () => (
  <nav>
    <Link href="/checkout" prefetch="hover">
      Checkout
    </Link>
    <Link href="/pricing" prefetch="viewport" prerender>
      Pricing
    </Link>
    <Link data-absolute-navigation="off" href="/legacy" prefetch="none">
      Legacy page
    </Link>
  </nav>
);
SVELTE
<script lang="ts">
  import Link from '@absolutejs/absolute/svelte/router/Link.svelte';
</script>

<nav>
  <Link to="/store" prefetch="hover">Back to the store</Link>
  <Link to="/pricing" prefetch="viewport" prerender>Pricing</Link>
  <Link to="/legacy" prefetch="none" data-absolute-navigation="off">
    Legacy page
  </Link>
</nav>

Prefetching is skipped when the user has Save-Data on, is on a 2G connection, or has asked for reduced data.

#Opting Out

Add data-absolute-navigation="off" to a link, or to any parent, for a normal page load.

HTML
<!-- On a link or on any parent element -->
<a data-absolute-navigation="off" href="/legacy">Legacy page</a>

The browser also handles the click itself for modifier and middle clicks, a target other than _self, download links, rel="external", other origins, and #hash links on the same page.

#Options and Events

enableNavigation takes two options. The first call's options apply.

TS
import { enableNavigation } from '@absolutejs/absolute/client/navigation';

enableNavigation({
  // Return false for a normal page load to this URL
  shouldIntercept: (url) => !url.pathname.startsWith('/admin'),
  // Default true. Skipped for users who prefer reduced motion.
  viewTransition: false
});

Use navigateDocument(href, { replace }) to navigate from code. The layer fires absolute:before-navigate and absolute:after-navigate on window, with url and type in detail. before-navigate can be cancelled, except for back and forward.

TS
import { navigateDocument } from '@absolutejs/absolute/client/navigation';

window.addEventListener('absolute:before-navigate', (event) => {
  // Cancel link and programmatic navigations
  if (hasUnsavedChanges()) event.preventDefault();
});

window.addEventListener('absolute:after-navigate', (event) => {
  if (event instanceof CustomEvent) console.log('now on', event.detail.url);
});

const outcome = await navigateDocument('/checkout', { replace: true });
// 'swapped' | 'reloaded' | 'superseded' | 'cancelled'
OutcomeMeaning
'swapped'The target page replaced the current one in place.
'reloaded'The browser did a normal page load instead.
'superseded'A newer navigation started before this one finished.
'cancelled'An absolute:before-navigate listener called preventDefault().

isNavigationEnabled() tells you whether the layer is on. disableNavigation() removes it.

#Supported Pages

Navigation without a reload works between React and Svelte pages, in both directions. Leaving an HTML or HTMX page is a normal page load.