Navigation

Hologram provides a seamless navigation experience by combining server-side rendering with client-side transitions. While each page is loaded fresh from the server, the framework uses the History PushState API and virtual DOM to ensure smooth transitions between pages.

Note: For information about defining routes for pages, see the Pages documentation.

Link Component

The Hologram.UI.Link component is the primary way to add navigation links in your templates. It supports both simple page navigation and passing parameters to the target page.

Basic usage:

<Link to={MyPage}>MyPage</Link>

With parameters:

<Link to={MyPage, a: 1, b: 2}>MyPage with params</Link>

Programmatic Navigation

Besides using the Hologram.UI.Link component in templates, you can also navigate programmatically in your actions using the put_page/2 and put_page/3 functions.

Basic navigation:

put_page(component, MyPage)

Navigation with parameters:

put_page(component, MyPage, a: 1, b: 2)

Navigation Behavior

Hologram implements several optimizations to make page transitions feel instant:

Prefetching

When a user interacts with a link, Hologram starts prefetching the target page on the $pointer_down event. On the $click event that follows, the current page is replaced with the prefetched content, making the transition feel instantaneous. A link followed without a pointer press, like from the keyboard or a screen reader, fetches the target page on the $click event instead.

Browser History

Hologram properly maintains the browser's history stack, ensuring that:

• Back and forward navigation restores a page the way the visitor left it, its state and scroll position included
• URL changes are reflected in the browser's address bar
• Navigating to a page loads it fresh from the server, ensuring up-to-date content
• Jumps to a #fragment within a page are left to the browser, so the page keeps its state

After a login or a logout, Back and forward don't restore a page left before it. The page renders the way a fresh visit would, so its middleware runs, and a page whose middleware requires a login redirects.

Benefits

This navigation approach combines the best of both worlds:

• Server-side rendering ensures SEO-friendly, up-to-date content
• Client-side transitions provide a smooth, app-like experience
• Fresh page loads guarantee content consistency
• Proper history management enables natural browser navigation