Links and routers

Chameleon links should change the page through your router in a single-page app instead of reloading the page. We show you here how to do that for each framework. Each link stays a real link throughout: it opens in a new tab on a middle click, shows its address on hover, and screen readers announce it as a link.

Which components are links⁠link

These components become links when you set href: the action card, button, icon button, assist chip, suggestion chip, input chip, list item, menu item, and navigation tab. Each one also takes target, rel, and download, which mean what they mean on an HTML anchor.

A disabled or soft-disabled link doesn't navigate. Every link opens in the same tab unless you set target.

Why your router needs to be told⁠link

A router that handles links by itself listens for clicks on the page and looks for the clicked anchor. A Chameleon component keeps its anchor inside itself, where that search can't reach, so without the steps below every click is a full page load. The page still works; it just reloads.

How you hand the click to your router depends on your framework.

React⁠link

Wrap your app in ChameleonRouterProvider and give it your router's navigate function. Every link component beneath it then navigates through the router when its link points inside the app, meaning the same origin and the same tab. The browser handles any other link, and any click with a modifier key held.

The provider calls navigate with the path, query, and hash, as a string.

React Router⁠link

import { Outlet, useNavigate } from "react-router";
import { ChameleonRouterProvider } from "@materia-technologies-inc/chameleon-components-react";

export function Layout() {
  const navigate = useNavigate();
  return (
    <ChameleonRouterProvider navigate={navigate}>
      <Outlet />
    </ChameleonRouterProvider>
  );
}

useNavigate works only inside the router, so the provider goes in a layout route rather than above the router.

Next.js⁠link

The App Router's useRouter is client-only, so the provider lives in a client component that your root layout renders.

"use client";
import { useRouter } from "next/navigation";
import { ChameleonRouterProvider } from "@materia-technologies-inc/chameleon-components-react";

export function ChameleonRouting({ children }) {
  const router = useRouter();
  return <ChameleonRouterProvider navigate={router.push}>{children}</ChameleonRouterProvider>;
}

TanStack Router⁠link

TanStack's navigate takes an options object, so pass the path as href.

import { Outlet, useNavigate } from "@tanstack/react-router";
import { ChameleonRouterProvider } from "@materia-technologies-inc/chameleon-components-react";

export function Layout() {
  const navigate = useNavigate();
  return (
    <ChameleonRouterProvider navigate={(path) => navigate({ href: path })}>
      <Outlet />
    </ChameleonRouterProvider>
  );
}

Handle one link yourself⁠link

Every link component also takes onNavigate. Where you set it, it replaces the provider's navigation for that one link, and Chameleon calls it only for a link inside the app. By the time it runs, Chameleon has already canceled the browser's navigation.

<CrListItem href="/orders/42" onNavigate={(detail) => openOrderPanel(detail.href)}>
  Order 42
</CrListItem>

onLinkActivate runs first, for every link followed in the same tab. Call preventDefault() on its event to stop both the browser and the router.

Blazor⁠link

Blazor needs no setup. A link component whose Href points inside the app (the same base address, opening in the same tab) cancels the browser's navigation and calls NavigationManager.NavigateTo. Your routes render as they would for a NavLink.

To navigate differently for one link, set OnNavigate. It replaces the NavigateTo call and Chameleon calls it only for a link inside the app.

<CbListItem TItem="string" Href="/orders/42" OnNavigate="OpenOrderPanel">Order 42</CbListItem>

@code {
    private string? _selectedOrder;

    private void OpenOrderPanel(LinkActivateEventArgs args) => _selectedOrder = args.Href;
}

The component raises OnLinkActivate first, for every link followed in the same tab, with the same Href, Target, Download, and Rel.

Web components⁠link

With the Navigation API⁠link

routeNavigations gives your router every navigation inside the app, from any link on the page, Chameleon's or your own. It returns a function that stops the routing.

import { routeNavigations } from "@materia-technologies-inc/chameleon-components-web";

const stop = routeNavigations((url) => router.render(url));

The Navigation API is in Chrome and Edge from version 102, Safari from 26.2, and Firefox from 147. In an older browser, routeNavigations does nothing, and links load pages normally until you add the listener below.

By the time your function runs, the address bar already shows the new address. Render the page for it. If your router insists on updating history itself, have it replace the current entry, not push a new one, or the back button needs two presses.

routeNavigations leaves to the browser everything that isn't a page change inside the app:

• Links to other origins
• Downloads
• Links within the page
• Form posts
• Back and forward
• Reloads
• History updates your router makes itself

Pass a filter to leave more to the browser:

routeNavigations((url) => router.render(url), {
  filter: (url) => !url.pathname.startsWith("/api/"),
});

With a link-activate listener⁠link

Every link component fires link-activate just before the browser follows it in the same tab. The event bubbles out of the component and you can cancel it, so one listener on the document handles every Chameleon link on the page.

document.addEventListener("link-activate", (event) => {
  const url = new URL(event.detail.href, location.href);
  if (url.origin !== location.origin) {
    return;
  }
  event.preventDefault();
  router.navigate(url.pathname + url.search + url.hash);
});

A component doesn't fire it for a click with a modifier key or the middle button, a link that opens in another tab, a download, or a disabled link. The browser handles those as it would for any anchor.

event.detail carries:

Finding a link in your own click handler⁠link

If your router already has a click listener on the document, resolveChameleonLink(event) finds the Chameleon link a click came through, in place of the anchor the router would look for. It returns null when there's none, or when the link can't navigate: it's disabled or soft-disabled, or it's a navigation tab in a tab list.

import { resolveChameleonLink } from "@materia-technologies-inc/chameleon-components-web";

document.addEventListener("click", (event) => {
  const link = resolveChameleonLink(event);
  if (link && link.target === "" && link.download === null) {
    // link.href is the address; link.host is the component
  }
});

After the page changes⁠link

A full page load moves focus to the new page and scrolls it to the top, so a screen reader announces the change. A routed navigation does only what your router does, so check what yours does.