Coder Legion - Recent posts tagged routing

TanStack Start Layouts Explained (Pathless Layout Routes + Outlet)

Mon, 28 Sep 2026 06:41:48 +0000

Layouts let us customize sections of our app based on their purpose, their content, or the look and feel we want. They give us the flexibility to mix things up, get more creative, and offer a really great UI/UX experience to our users.

Navigation benefits the most. With layouts we can change the nav style, content, and links based on the page a user is on. We also get to write DRY (Don't Repeat Yourself) code: build a navigation component once, call it in a layout, and when something needs to change, edit one file and the change propagates throughout the app.

So, enough talk. Let's crack on.

Where we're picking up

This post continues the app we've been building in this series. If you're here for the first time, start with the first post in this TanStack Start series. If you want to keep up with the full stack, you can also go through the Directus series.

Create a simple header

Open the app in VS Code. In src/components, create a file called MainHeader.tsx with the following code:

export default function MainHeader() {
  return <div></div>
}

Inside the div, add another div containing an h1 and a p tag:

export default function MainHeader() {
  return (
    <div>
      <div>
        <h1>Logo</h1>
        <p>This is our navigtion menu</p>
      </div>
    </div>
  )
}

Yes, "navigtion" is missing an "a". That's deliberate, and you'll see why shortly.

Now add some Tailwind CSS classes:

export default function MainHeader() {
  return (
    <div>
      <div className="flex items-center justify-between p-8">
        <h1 className="uppercase font-bold text-2xl">Logo</h1>
        <p>This is our navigtion menu</p>
      </div>
    </div>
  )
}

Approach 1: paste the header into every route

Copy the div and its content from MainHeader:

<div>
  <div className="flex items-center justify-between p-8">
    <h1 className="uppercase font-bold text-2xl">Logo</h1>
    <p>This is our navigtion menu</p>
  </div>
</div>

Paste it into each route component (index, about, and products) above the first h1. For example, in the home route:

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({ component: Home })

function Home() {
  return (
    <div className="p-8">
      <div>
        <div className="flex items-center justify-between p-8">
          <h1 className="uppercase font-bold text-2xl">Logo</h1>
          <p>This is our navigtion menu</p>
        </div>
      </div>

      <h1 className="font-bold text-5xl text-slate-700">Home</h1>
    </div>
  )
}

You should now see the header on every page. As a reminder from the previous post, the home page is http://localhost:3000, and for every other page you add a forward slash and the page name, like /about and /products.

We have a site header. But this isn't a good implementation. Remember the misspelled word? To fix it, we'd have to visit every route and correct it. That's not efficient. Delete the header from every page and let's try something better.

Approach 2: use the MainHeader component

Our site should be back to how it was, without a header. This time, import the MainHeader component in every route and place it above the first h1:

import MainHeader from '@/components/MainHeader'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/about')({
  component: RouteComponent,
})

function RouteComponent() {
  return (
    <div className="p-8">
      <MainHeader />
      <h1 className="font-bold text-5xl text-slate-700">About</h1>
    </div>
  )
}

Now go into MainHeader.tsx and fix "navigtion" to "navigation". One fix, one file, and it shows up across the app. That's a real improvement.

It's still not ideal, though, because we have to remember to add MainHeader to every route component we create.

Approach 3: put the header in `__root.tsx`

There's a way to call the header once and have it available to every route. Remember __root.tsx? It wraps our entire app using the children prop. What if we place the header above children?

First, remove <MainHeader /> from your route components. Then update the root:

// Only the code relevant to this discussion is shown
import MainHeader from '@/components/MainHeader'

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <QueryClientProvider client={queryClient}>
          <MainHeader />
          {children}
        </QueryClientProvider>
        <Scripts />
      </body>
    </html>
  )
}

Visit the home page and you'll see the logo on the left and the nav menu on the right, above the page content. Visit /about and /products and the header is there too.

Is this great? Well, not quite. It's efficient: the component is called once and shows on every route, and changes happen in one place. The limitation is flexibility. If we want a different header depending on the page the user is on, we have to add complexity to this file. A good rule of thumb is to keep __root.tsx as clean and lean as possible.

So delete the header and its import from __root.tsx. There's an even better way: layouts.

Layouts

With layouts you get the efficiency of editing one file and having the change ripple through your app, but you can also have different layouts for different pages and still edit just one file for each.

In src/components, create a layouts folder. Inside it, create AppLayout.tsx:

import { Outlet } from '@tanstack/react-router'
import MainHeader from '../MainHeader'

export default function AppLayout() {
  return (
    <div>
      <MainHeader />
      <div className="max-w-7xl mx-auto p-4">
        <Outlet />
      </div>
    </div>
  )
}

The only part that might seem strange is Outlet. It works the same way as the children prop in __root.tsx: it's a placeholder where the matched child route gets rendered. That's how a layout wraps a route.

Create the layout route

In src/routes, create a file called _appLayout.tsx. TanStack Start will scaffold the route for you. You may see a path conflict error with the home route. Don't worry about it, it clears up once we're done. Update the file:

import AppLayout from '@/components/layouts/AppLayout'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_appLayout')({
  component: () => {
    return <AppLayout />
  },
  notFoundComponent: () => {
    return <p>This page doesn't exist!</p>
  },
})

Here's what the two options do:

component: what actually renders when a child route matches. Since this is a layout route, AppLayout contains an <Outlet />, the placeholder where whichever child route matched gets rendered.
notFoundComponent: defines not-found handling scoped to this layout. It lets different sections of your app show contextually appropriate "not found" messaging instead of one generic message everywhere.

Move your routes under the layout

How do we add pages to this layout? Through the file names. Rename your route files like this:

_appLayout.index.tsx
_appLayout.about.tsx
_appLayout.products.tsx

Then remove <MainHeader /> from each route component (if you haven't already), since the layout now provides it. The route path inside each file, like createFileRoute('/_appLayout/about'), is updated for you by the router plugin while the dev server is running.

You'll notice the whole app layout has changed. The pages are now displayed at a fixed width instead of the full page. What's happening is that the route components are now nested inside the _appLayout route. You don't see _appLayout in the browser's URL because the leading underscore tells TanStack Router this is a pathless route, in other words, a layout route.

To change the header, edit the header component and it renders across the app. To change the layout structure, change one file.

What if I need a different header for a specific page?

Layouts have you covered. In src/components, create another header component called ProductsHeader.tsx:

export default function ProductsHeader() {
  return (
    <div>
      <div className="flex items-center justify-between p-8">
        <h1 className="uppercase font-bold text-2xl">Logo</h1>
        <p>This is the Products menu</p>
      </div>
    </div>
  )
}

Now create a layout component for it in src/components/layouts called ProductsLayout.tsx:

import { Outlet } from '@tanstack/react-router'
import ProductsHeader from '../ProductsHeader'

export default function ProductsLayout() {
  return (
    <div>
      <ProductsHeader />
      <div className="max-w-7xl mx-auto p-4">
        <Outlet />
      </div>
    </div>
  )
}

The ProductsHeader is now part of ProductsLayout. To make the products route a child of this layout, rename its file from _appLayout.products.tsx to:

_productsLayout.products.tsx

Then, in src/routes, create _productsLayout.tsx:

import ProductsLayout from '@/components/layouts/ProductsLayout'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_productsLayout')({
  component: () => {
    return <ProductsLayout />
  },
  notFoundComponent: () => {
    return <p>This page doesn't exist!</p>
  },
})

Check the app. The home and about pages share the same header, while the products page has a different one. You could just as easily give the products page an entirely different layout structure, not just a different header.

Summary

Here's what we covered:

Pasting a header into every route works, but a single typo means editing every page.
A reusable component fixes the typo problem, but you still have to add it to every route by hand.
Putting the header in __root.tsx shows it everywhere from one place, but it makes your root file busier, and it's inflexible when pages need different headers.
Layouts give you the best of both: a pathless layout route (a file starting with _) renders a layout component, and that component uses <Outlet /> to render whichever child route matched.

A few things to remember:

The underscore prefix makes a route pathless, so it wraps its children without adding to the URL.
A route file's name decides which layout it lives under, for example _appLayout.about.tsx versus _productsLayout.products.tsx.
You can create as many layouts as your app needs, each with its own header, structure, and not-found handling, and still only edit one file per layout.

In the next post we'll keep building on this app. If you found this helpful, leave a comment or a reaction, and follow the series so you don't miss it.

Happy coding! 🚀

Next.js 16 Routing Explained: A Complete Beginner's Guide (2026)

Wed, 29 Jul 2026 19:00:00 +0000

If you've ever opened a Next.js project and wondered why a folder named (marketing) doesn't show up in the URL, or what on earth @modal means in a file path — you're not alone. Routing is one of the first things you touch in Next.js, and it's also one of the most misunderstood parts of the App Router.

The good news? Once you understand the core idea — folders are routes — everything else is just variations on that one theme.

By the end of this guide, you'll understand every major routing pattern in Next.js 16: static routes, dynamic routes, nested layouts, route groups, parallel routes, intercepting routes, and catch-all segments. We'll build real examples for each one, not just theory.

Pattern	Example	URL
Static	`about/page.tsx`	`/about`
Dynamic	`[slug]/page.tsx`	`/post/hello`
Catch-all	`[...slug]/page.tsx`	`/docs/a/b`
Optional Catch-all	`[[...slug]]/page.tsx`	`/docs` or `/docs/a`
Route Group	`(marketing)/pricing/page.tsx`	`/pricing`
Parallel Route	`@analytics/page.tsx`	Slot
Intercepting Route	`(.)photo/[id]/page.tsx`	Modal

Why Next.js Routing Feels Confusing at First

Unlike React Router or other client-side routers, Next.js doesn't use a config file or a <Routes> component to define your pages. Instead, it uses your file system as the source of truth. The folder structure inside app/ directly maps to the URLs your site responds to.

This is powerful once it clicks, but it also means special folder names (like [slug], (group), or @slot) carry real meaning. Misreading one of these conventions is usually where beginners get stuck.

Let's go through them one at a time.

The Basics: How Folders Become URLs

In the App Router, every route lives inside the app/ directory, and a folder only becomes a visible page when it contains a page.tsx file.

// app/about/page.tsx
export default function AboutPage() {
  return <h1>About Us</h1>;
}

This single file creates the route /about. No router config, no manual registration — Next.js scans the folder tree and wires it up automatically.

💡 Tip: A folder without a page.tsx inside it does not create a route. It might just be there to hold layouts, components, or nested routes.

Special Files You'll See in a Route Folder

File	Purpose
`page.tsx`	Makes the route publicly accessible (the actual UI)
`layout.tsx`	Wraps the page (and its children) with shared UI
`loading.tsx`	Shown automatically while the page is loading
`error.tsx`	Catches errors thrown inside that route segment
`not-found.tsx`	Shown when `notFound()` is called or no route matches

We'll use most of these as we go.

Nested Routes

Want /blog/getting-started to be a real page? Just nest folders:

app/
└── blog/
    ├── page.tsx              → /blog
    └── getting-started/
        └── page.tsx          → /blog/getting-started

// app/blog/getting-started/page.tsx
export default function GettingStartedPage() {
  return <h1>Getting Started With Next.js</h1>;
}

Each folder level adds a segment to the URL path. There's no limit to how deep you can nest — Next.js just keeps following the folders.

Dynamic Routes

Static folders are great until you need a page per blog post, per product, or per user. That's where dynamic routes come in, using square brackets in the folder name.

app/
└── blog/
    └── [slug]/
        └── page.tsx          → /blog/anything-here

// app/blog/[slug]/page.tsx
interface BlogPostPageProps {
  params: Promise<{ slug: string }>;
}

export default async function BlogPostPage({ params }: BlogPostPageProps) {
  const { slug } = await params;

  return <h1>Reading post: {slug}</h1>;
}

Visiting /blog/nextjs-routing-guide renders this page with slug equal to "nextjs-routing-guide".

⚠️ Common Mistake: In Next.js 16, params is a Promise, not a plain object. You must await it before reading values — forgetting this is one of the most common upgrade bugs when migrating from older Next.js versions.

Generating Pages at Build Time

If you know all possible slugs ahead of time (e.g. you're reading blog posts from the file system or a CMS), you can pre-render them at build time with generateStaticParams:

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getAllPosts();

  return posts.map((post) => ({
    slug: post.slug,
  }));
}

This tells Next.js "here are all the dynamic values that exist — build a static page for each one" instead of rendering them on-demand at request time.

Catch-All and Optional Catch-All Routes

Sometimes one dynamic segment isn't enough. Maybe you want /docs/a, /docs/a/b, and /docs/a/b/c to all hit the same page, with the rest of the path available as an array. That's a catch-all route, written with three dots inside the brackets.

app/
└── docs/
    └── [...slug]/
        └── page.tsx

// app/docs/[...slug]/page.tsx
interface DocsPageProps {
  params: Promise<{ slug: string[] }>;
}

export default async function DocsPage({ params }: DocsPageProps) {
  const { slug } = await params;

  // For /docs/a/b/c, slug = ["a", "b", "c"]
  return <h1>Docs path: {slug.join(" / ")}</h1>;
}

There's also an optional catch-all, which uses double brackets [[...slug]]. The difference: with optional catch-all, /docs itself (with no extra segments) also matches the same page, instead of returning a 404.

app/
└── docs/
    └── [[...slug]]/
        └── page.tsx          → matches /docs, /docs/a, /docs/a/b, etc.

💡 Tip: Catch-all routes are exactly how Clerk's [[...sign-in]] pattern works under the hood — one page handles every sub-step of the auth flow.

Layouts: Shared UI Across Routes

A layout.tsx wraps every page inside its folder (and all nested folders below it) without losing state on navigation — things like a sidebar won't re-render or flicker when you click between pages.

// app/blog/layout.tsx
export default function BlogLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="flex gap-6">
      <aside className="w-48">Blog Sidebar</aside>
      <main className="flex-1">{children}</main>
    </div>
  );
}

Every page under app/blog/ — including [slug]/page.tsx — now renders inside this layout automatically. Layouts nest too: the root app/layout.tsx wraps everything, and a deeper layout wraps just its own subtree.

⚠️ Common Mistake: Layouts don't re-render when you navigate between sibling pages that share them. If you need something to reset per-page (like scroll position or a key-based remount), you'll need to handle that explicitly — layouts are persistent by design.

Route Groups: Organizing Without Affecting the URL

Sometimes you want to organize routes into logical folders — like separating marketing pages from authenticated dashboard pages — without those folder names showing up in the URL. Wrapping a folder name in parentheses does exactly that.

app/
├── (marketing)/
│   ├── layout.tsx        → navbar + footer
│   ├── page.tsx          → /
│   └── pricing/
│       └── page.tsx      → /pricing
│
└── (dashboard)/
    ├── layout.tsx        → sidebar + topbar
    └── settings/
        └── page.tsx      → /settings

Notice that /pricing doesn't become /marketing/pricing — the parentheses tell Next.js "this folder is for organization only, ignore it in the URL." This is exactly how you'd separate a public marketing layout from a private dashboard layout, each with completely different navigation chrome.

💡 Tip: Route groups are also useful for giving the same URL segment multiple layout options during development, or for splitting large apps into logical sections for your team without touching the live URL structure.

Parallel Routes: Rendering Multiple Pages at Once

This is where things get genuinely interesting. Parallel routes let you render two or more independent pages in the same layout, side by side — each with its own loading and error state. You define them with a @ prefix, called a "slot."

Imagine a dashboard that shows an analytics chart and a notifications feed at the same time, but each one loads independently:

app/
└── dashboard/
    ├── layout.tsx
    ├── page.tsx
    ├── @analytics/
    │   └── page.tsx
    └── @notifications/
        └── page.tsx

// app/dashboard/layout.tsx
export default function DashboardLayout({
  children,
  analytics,
  notifications,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  notifications: React.ReactNode;
}) {
  return (
    <div className="grid grid-cols-2 gap-4">
      <div className="col-span-2">{children}</div>
      <div>{analytics}</div>
      <div>{notifications}</div>
    </div>
  );
}

Each slot (@analytics, @notifications) is passed into the layout as a prop, matching its folder name. Next.js renders them all in parallel — if @notifications is still loading, it won't block @analytics from showing up.

⚠️ Common Mistake: Slot folders need their own page.tsx (or a default.tsx as a fallback) — if a slot has no matching route for the current URL and no default.tsx, Next.js will throw a 404 for the entire layout, not just that slot.

// app/dashboard/@notifications/default.tsx
export default function Default() {
  return null; // fallback when no route matches this slot
}

Intercepting Routes: Modals That Feel Like Pages

Ever clicked a photo on Instagram and seen it open in a modal — but if you refresh that same URL, it loads as a full standalone page instead? That's an intercepting route, and Next.js supports this pattern natively using (.)-style folder prefixes.

app/
├── feed/
│   ├── page.tsx
│   └── @modal/
│       ├── default.tsx
│       └── (.)photo/
│           └── [id]/
│               └── page.tsx     → intercepted modal view
└── photo/
    └── [id]/
        └── page.tsx              → full page (direct visit / refresh)

The convention:

(.) intercepts a route at the same level
(..) intercepts one level above
(..)(..) intercepts two levels above
(...) intercepts from the root

// app/feed/@modal/(.)photo/[id]/page.tsx
export default async function PhotoModal({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;

  return (
    <div className="fixed inset-0 flex items-center justify-center bg-black/50">
      <div className="bg-white p-6 rounded-xl">Photo {id} (modal view)</div>
    </div>
  );
}

So when a user clicks a photo while browsing the feed, Next.js intercepts the navigation and shows the modal. But if they paste that same /photo/123 URL directly into a new tab, Next.js skips the interception and renders the real app/photo/[id]/page.tsx as a normal full page.

💡 Tip: Intercepting routes are almost always paired with parallel routes (the @modal slot) — the slot is what lets the modal render on top of the feed instead of replacing it.

Linking Between Routes

All of this routing is useless without navigation. Always use Next.js's Link component instead of a plain <a> tag — it enables client-side transitions and automatic prefetching.

import Link from "next/link";

export default function Nav() {
  return (
    <nav>
      <Link href="/blog">Blog</Link>
      <Link href="/blog/nextjs-routing-guide">A Specific Post</Link>
    </nav>
  );
}

For programmatic navigation (e.g. redirecting after a form submits), use the useRouter hook in a Client Component:

"use client";

import { useRouter } from "next/navigation";

export default function SubmitButton() {
  const router = useRouter();

  return (
    <button onClick={() => router.push("/dashboard")}>
      Go to Dashboard
    </button>
  );
}

Frequently Asked Questions

Do route groups affect performance?

No. Route groups are purely an organizational tool at build time — they don't add extra network requests, extra DOM nodes, or any runtime cost. They simply change how your files are organized without changing the URL.

Can I combine dynamic routes with route groups?

Yes, and it's common. For example, app/(dashboard)/projects/[id]/page.tsx gives you /projects/123 while keeping the dashboard layout grouping intact.

What's the difference between `loading.tsx` and a parallel route's own loading state?

loading.tsx shows a fallback for an entire route segment while its data loads. Inside parallel routes, each slot (@analytics, @notifications, etc.) can have its own loading.tsx, so one slot can show a spinner while another already displays its content — they load independently.

Why did my page 404 after adding a parallel route slot?

This usually means a slot (like @modal) has no page.tsx matching the current URL and no default.tsx fallback. Add a default.tsx that returns null (or some neutral fallback UI) to fix it.

Can intercepting routes work without parallel routes?

Technically you can intercept into the main children slot, but in practice almost every real-world use case (modals, lightboxes, previews) pairs intercepting routes with a parallel @slot so the intercepted content renders alongside the existing page instead of replacing it.

Wrapping Up

Next.js 16's App Router routing system might look intimidating with all its special folder syntax, but it really boils down to a handful of conventions: brackets for dynamic segments, dots for catch-alls, parentheses for invisible grouping, and @ for parallel slots. Once you've built each pattern once with your own hands, reading someone else's project structure stops feeling like decoding a puzzle.

From here, a natural next step is wiring up authentication-protected routes using these same patterns — check out the Clerk guide below to see route groups and catch-all routes used together in a real auth flow.

Useful Resources

Continue Learning

Routing in Alusus WebPlatform

Mon, 27 Apr 2026 00:34:02 +0000

Routing is one of the important elements in any web library, and it is also one of the things that the Alusus language handles in a distinctive way. Routing in WebPlatform provides the following features:

Automatically loading the page that matches the current URL.
Navigating between pages without reloading.
Updating the address bar when navigating between pages.
Responding to the browser's back button without reloading the site.
Applying transition animations when navigating between pages and allowing the user to create their own custom animations.
Providing two navigation modes: a replacement mode where one page replaces another, and a stacking mode where a page is loaded on top of the current one with the intent of dismissing it later to return to the previous page.

The last point is what we would like to focus on in this article, as WebPlatform supports these features in a unique way that I have not seen in any other web library.

The Switcher and the Stack

WebPlatform supports routing operations by providing two fundamental components dedicated to this purpose: Switcher and Stack. The Switcher allows switching between pages by removing the current page from memory and creating a different one, while the Stack allows the user to load pages on top of each other to enable returning to previous pages later without losing their data and state.

The user can make these two components fill the entire screen or just part of it. Multiple instances of each can be created and combined within an application in any desired configuration, allowing great flexibility in designing any site map. For example, a user can create a Stack with a Switcher inside it, where the Switcher is responsible for switching between the site's pages, while the Stack is used to display popup windows or temporary pages that appear on top of the site (i.e., on top of the Switcher) regardless of which page the user is currently on.

The user can also do the reverse: create a Switcher and embed a Stack within one of its views. In this case, the Stack is used to display a temporary window that appears on top of that specific page only, not the entire site — meaning that navigating to another page removes the current page along with its associated popup.

Multiple Switchers or Stacks can also be created as desired and in any configuration. For example, a main Switcher can be created for the site's primary pages, and then within one of those pages a secondary Switcher can be embedded to handle navigation between sub-pages within that main page.

Routing

The two base classes Switcher and Stack are only responsible for providing the view-switching operation, which is the fundamental mechanism on which routing is built — but they do not provide true routing that binds a URL to the requested page. That responsibility falls on the RoutingSwitcher and RoutingStack classes, which rely on the former two to provide view transitions and link them to the browser's address bar.

In both classes, the user needs to specify a set of routes along with a closure for each route that creates the desired view for that route. Both classes use regular expressions to determine which view to display, with a difference in the algorithm used as described below.

Before diving into details, it should be noted that all of this assumes you place the entire site under a single UI endpoint — meaning that instead of relying on multiple functions annotated with @uiEndpoint, each dedicated to a specific path, you instead use a single function that covers all the paths handled by the two routing components mentioned above. This is done by using a wildcard * in the endpoint path. For example:

@uiEndpoint["/*"]
@title["WebPlatform Example"]
func main {
}

In the example above, we tell WebPlatform to route every path starting with / to the same function, effectively moving all routing from the server to the browser. Of course, you can restrict the scope to a smaller path, such as using a specific prefix followed by * — for instance, /ui/* — to tell WebPlatform that any path beginning with /ui/ should be routed to that function.

It is worth noting that WebPlatform uses priorities when matching paths: it gives priority to back-end endpoint paths, then resource paths, before UI endpoint paths. Therefore, setting the UI endpoint path to /* will not prevent access to an API endpoint like /api/login, for example.

RoutingSwitcher

The algorithm used by RoutingSwitcher is very straightforward: it iterates through the defined routes in sequence, matching each route's regular expression against the full current URL. If a match is found, that view is displayed and iteration stops. If no match is found, it continues to the next definition, and so on.

RoutingSwitcher().{
    route("^/one$") = closure(RoutePayload): SrdRef[Widget] {
        return View1();
    };
    route("^/two$") = closure(RoutePayload): SrdRef[Widget] {
        return View2();
    };
    route("^/three$") = closure(RoutePayload): SrdRef[Widget] {
        return View3();
    };
}

But what if we want to embed a RoutingSwitcher inside another one — for instance, if View3 contains another Switcher for navigating between inner pages? Suppose the sub-paths are:

/three/subview1
/three/subview2

In this case, we need to account for these paths in the regular expressions of both the outer and inner Switchers. We change the outer Switcher's route from ^/three$ to ^/three — i.e., by removing the $ — to allow View3 to be created when sub-paths match. Otherwise, the inner Switcher would never be instantiated and the inner pages could never be shown. Likewise, the inner Switcher's routes must account for the presence of the three segment in the URL, either by writing the full URL or by writing the sub-path without using the ^ anchor.

RoutingStack

The routing Stack works differently. Instead of iterating through all views looking for the one matching view, it does the opposite: it iterates through all views looking for the first non-matching view. It keeps creating views one on top of another until it reaches a view whose path does not match, at which point it stops. Therefore, the user must ensure that each view defines a path that matches all the views before it, otherwise it will never be displayed. For example:

RoutingStack().{
    route(String("^/one")) = closure(RoutePayload): SrdRef[Widget] {
        return View1();
    };
    route(String("^/one/edit")) = closure(RoutePayload): SrdRef[Widget] {
        return Editor();
    };
};

If the current path is /one, only View1 is displayed. If the path is /one/edit, then View1 is displayed with Editor stacked on top of it.

What if you have more than one sub-view that you want to display on top of the current view — say /one/edit and /one/share? To handle this, you can make the sub-view a Switcher that decides which of the two views to load. For example:

RoutingStack().{
    route(String("^/one")) = closure(RoutePayload): SrdRef[Widget] {
        return View1();
    };
    route(String("^/one/(edit|share)")) = closure(RoutePayload): SrdRef[Widget] {
        return RoutingSwitcher().{
            route("^/one/edit$") = closure(RoutePayload): SrdRef[Widget] {
                return Editor();
            };
            route("^/one/share$") = closure(RoutePayload): SrdRef[Widget] {
                return Share();
            };
        };
    };
};

Relying on traditional hyperlinks allows navigation between pages, but clicking a traditional hyperlink causes the page to reload. To avoid reloading, we use the pushLocation function from the Window class. For example:

Window.instance.pushLocation("/one/edit");

This updates the address bar in the browser and then navigates to the requested view. WebPlatform will take care of displaying the new view with the appropriate transition animations. Pressing the browser's back button afterward will return to the previous page with transition animations, without reloading the page.

This does not mean hyperlinks should be avoided entirely — they serve an important purpose: informing search engines about the pages that can be navigated to. If the page is private and not meant for search engine indexing, hyperlinks can be omitted. But if it is a public page that we want search engines to index, it is better to use hyperlinks alongside pushLocation, as in this example:

Hyperlink().{
    url = String("/about");
    setChild(Text(String("About")));
    onClick.defaultPrevented = 1;
    onClick.connect(closure (ref[Widget], ref[Int]) {
        Window.instance.pushLocation("/about");
    });
};

In the example above, we use a hyperlink but override its click behavior to use pushLocation instead of relying on the default behavior that reloads the page. This way we get the best of both worlds: smooth navigation with animations and no reloading, plus links that search engines can read.

Animations

The Switcher and Stack both support transition animations when moving from one view to another, and they allow the user to specify these animations — either by defining a custom animation style or by choosing from a set of predefined effects. Animations are set using the setTransition function available in both RoutingSwitcher and RoutingStack. It accepts two arguments: the first specifies the animation when transitioning to a higher view (according to the order in the view list), and the second specifies the animation for the reverse direction. For example, to set a transition on the Switcher:

setTransition(
    createSlideSwitcherTransition(0.5, 0, 0),
    createSlideSwitcherTransition(0.5, 0, 1)
);

The function above uses a slide effect, meaning the new view slides in from and out to the edge of the screen. The first argument specifies the duration of the slide in seconds, the second specifies whether the slide is vertical (1) or horizontal (0), and the third specifies the direction of movement — entering or exiting.

The following functions are available for creating Switcher animations:

createSlideSwitcherTransition
createFadeSwitcherTransition

And the following for Stack animations:

createSlideStackTransition
createFadeStackTransition
createFadeWithScaleStackTransition

Creating your own custom animations is also straightforward. You can look at the definitions of these functions in the WebPlatform library to learn how to create your own animations.

Full Example

The following WebPlatform example demonstrates routing using these two components:
https://github.com/Alusus/WebPlatform/blob/main/Examples/routing_showcase.alusus