Router Breadcrumbs (Displayable Routes)

[allan-vera]

Hello,

First time suggesting a feature so please let me know if you need any more details.

For my Router Layout Component, I am doing something like this.

<div>
   <Breadcrumbs breadcrumbs={breadcrumbs} />
   <Outlet />
</div>

And, I am currently generating breadcrumbs like so:

const router = useRouterState();
const { matches } = router;
const pathNames = matches.map((match) => match.routeId);
const breadcrumbs: string[] = condensePathNames(routeIds);

export function condensePathNames(pathNames: string[]) {
  const orderedPathNames = new Set<string>();

  for (let i = 0; i < pathNames.length; i++) {
    let pathName = pathNames[i];

    // React router changes "/" to "__root__", so change back
    if (pathName === "__root__") pathName = "/";

    // ignore paths that end in / unless its "/"
    if (pathName !== "/" && pathName[pathName.length - 1] === "/") break;

    // ignore paths that are already added
    // (shouldn't be nec but just in case)
    if (orderedPathNames.has(pathName)) break;

    orderedPathNames.add(pathName);
  }

  return Array.from(orderedPathNames);
}

And in my Breadcrumbs component I have to do something like this to replace paramIds with their actual value

const BREADCRUMBS_MAP: Record<string, string> = {
  // DASHBOARD
  "/": "Dashboard",

  // USERS
  "/users": "Users",
  "/users/$userId": "User Detail",
  "/users/create": "Create User",
  "/users/$userId/edit": "Edit User",
  }

<BreadcrumbLink
                  as={i === paths.length - 1 ? undefined : Link}
                  to={replacePathParamWithValue(
                    path,
                    matches[Object.keys(matches).length - 1].params ?? null
                  )}
                >
                  {BREADCRUMBS_MAP[path as string]}
                </BreadcrumbLink>
                
 export function replacePathParamWithValue(
  path: string,
  params: Record<string, string>
) {
  // check to see if path includes $
  if (!path.includes("$") || !params) return path;

  const rawPaths = path.split("/");
  const paramKeys = Object.keys(params);
  const res = [];
  for (let i = 0; i < rawPaths.length; i++) {
    let rawPath = rawPaths[i];
    if (rawPath.includes("$")) {
      paramKeys.forEach(
        (pk: string) => (rawPath = rawPath.replace(`$${pk}`, params[pk]))
      );
    }
    res.push(rawPath);
  }

  return res.join("/");
}               

It works decently but as you can probably imagine, it's very fragile especially when I attempt to work with static nested paths (ie. ['/', '/users/$userId', '/users/$userId/'] <-- not sure why but '/users' got skipped. Is there currently a way I could easily get breadcrumbs from the router? If not, this is my suggested feature.

Ideally, we could be provided a way to provide displayable names for each of the routes, that way we could retrieve that displayable name of the route that could then be used for the breadcrumbs.

Thanks!

[allan-vera]

kind bump

[snewell92]

I'm imagining this as two simple utilities as an API to build breadcrumbs; a hook and a link component. Something like

useBreadcrumbs

interface BreadcrumbRoute {
  path: string;
  name: string; // where does this come from?
  // TODO any more?
}

export function useBreadcrumbs(): Array<BreadcrumbRoute> {
  // TODO MAGIC reactive

  return collectedBreadcrumbs;
}

and

BreadcrumbLink

type Props = PropsWithChildren<{link: BreadcrumbRouter}>;

export function BreadcrumbLink({ link, children }: Props) {
  // custom onclick handling that pops history

  // parent could pass name? do we just need path then
  return <Link to={link.path}>{children}</Link>;
  // can we use Link internally or since we are essentially pressing the browser's
  //  back button n times.
}

The "press browser back btn n times" feels correct, but probably has subtle things that are wrong about it (ie can you suspend routing or batch n back btn presses?).

[EwenQuim]

useBreadcrumbs() should definitely be in the library by default.

Not sure about that BreadcrumbLink component. Let the user code it for their needs?

[tigawanna]

This works for me

//use-tsr-breadcrumbs
import { useLocation } from "@tanstack/react-router";

export function useTSRBreadCrumbs() {
  const current = useLocation();

  const route_history = current.pathname
    .split("/")
    .filter((x) => x && x.length > 0);

  const breadcrumb_routes = route_history.reduce(
    (acc: { name: string; path: string }[], route) => {
      const prev_path = acc[acc.length - 1]?.path ?? "";
      acc.push({ name: route, path: `${prev_path}/${route}` });
      return acc;
    },
    [],
  );
  return { breadcrumb_routes };
}

//TSRBreadCrumbs.tsx

import { Link } from "@tanstack/react-router";
import { useTSRBreadCrumbs } from "./use-bread-crumbs";
import { ChevronRight } from "lucide-react";

interface TSRBreadCrumbsProps {}

export function TSRBreadCrumbs({}: TSRBreadCrumbsProps) {
  const { breadcrumb_routes } = useTSRBreadCrumbs();
  if(breadcrumb_routes.length<2)return null
  return (
    <div className="w-full flex flex-wrap md:justify-end gap-0.1 p-1">
      {breadcrumb_routes.map((crumb) => {
        if (breadcrumb_routes.length - 1 === breadcrumb_routes?.indexOf(crumb)) {
          return (
            <span key={crumb.path} className="text-xs bread-crumbs-links">
              {crumb.name}
            </span>
          );
        }
        return (
          <span key={crumb.path} className="flex gap-1 justify-center items-center">
            <Link className="text-xs bread-crumbs-links" to={crumb.path}>
              {crumb.name}
            </Link>
            <ChevronRight className="size-4" />
          </span>
        );
      })}
    </div>
  );
}

[allan-vera]

Going to be revisiting this at some point next week and will be able to take a deeper look then, but does this take ids into account as well? For example, users/:user_id/edit broken down to "Dashboard / Users / User Detail / Edit User"

[itsmejawad]

This is perfect!

[tigawanna]

Going to be revisiting this at some point next week and will be able to take a deeper look then, but does this take ids into account as well? For example, users/:user_id/edit broken down to "Dashboard / Users / User Detail / Edit User"

yup , it segments the whole path search params and params included

[allan-vera]

Sweet!! I'll look into refactoring my existing code at some point so it can adopt this. Also, it appears useLocation does not exist in the current version of tanstack router i am using so will need to upgrade that as well.

Thanks for taking a look!

[chorobin]

We've been trying to address breadcrumbs recently with some experimental changes with useMatches. The aim is to provide a type safe way to build breadcrumbs and similar things

Firstly useMatches returns discriminated union so its possible narrow matches based on fullPath or routeId. Secondly there is a isMatch type predicate that allows you filter and narrow matches based on the shape of a match. matches.filter(match => isMatch(match, 'context.crumb')) will narrow matches that have the crumb property in context

#2058

We have Breadcrumbs now in the kitchen sink example

https://github.com/TanStack/router/blob/main/examples/react/kitchen-sink-file-based/src/components/Breadcrumbs.tsx

It would be great to get some feedback

[NateHawk85]

First, I love the progress, and this library has made 99% of my issues with routing disappear. Unfortunately, Breadcrumbs is a big one that I haven't found a solid way past... yet. In my eyes, the core of this Breadcrumb issue is that useMatches doesn't return index routes, nor does there seem to be an option to include them in the results. For example, if I have a directory structure of

routes/
├─ __root.tsx
|
├─ teams/
│  ├─ index.tsx
│  ├─ $teamId.tsx
│  |
│  ├─ $teamId.players/
│  │  ├─ index.tsx
│  │  ├─ $playerId.tsx

When I run useMatches() within my Breadcrumbs component, I get 3 matches (vs 5 expected) with route ids:

• __root__
• (MISSING) /teams/
• /teams/$teamId
• (MISSING) /teams/$teamId/players/
• /teams/$teamId/players/$playerId

One implementation could be an includeIndex option flag (or something similar) for useMatches that would include those index routes when evaluating matches.

[chorobin]

It sounds like you want branches, not index routes? I think you need route.tsx here aswell as an index route for the branch to match

[gabbelobo]

Just to clarify for others having the same problem, to get the breadcrumbs to work properly, have the following structure:

routes/
├─ __root.tsx
|
├─ clients/
│  ├─ index.tsx
│  ├─ route.tsx
│  ├─ create.tsx

index.tsx

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

export const Route = createFileRoute('/clients/')({
  component: () => <div>Hello from '/clients</div>,
})

route.tsx

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

export const Route = createFileRoute('/clients')({
  loader: () => ({
    crumb: 'Clients',
  }),
})

create.tsx

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

export const Route = createFileRoute('/clients/create')({
  component: () => <div>Hello from '/clients/create</div>,
  loader: () => ({
    crumb: 'Create',
  }),
})

And the useMatches will match both index and create routes properly.

[Saidmuhammad2002]

is there any way to achieve same behaviour without making route file for each page

[tigawanna]

Hook

import { useLocation } from "@tanstack/react-router";

export function useTSRBreadCrumbs() {
  const current = useLocation();

  const route_history = current.pathname
    .split("/")
    .filter((x) => x && x.length > 0);

  const breadcrumb_routes = route_history.reduce(
    (acc: { name: string; path: string }[], route) => {
      const prev_path = acc[acc.length - 1]?.path ?? "";
      acc.push({ name: route, path: `${prev_path}/${route}` });
      return acc;
    },
    [],
  );
  return { breadcrumb_routes };
}

Usage

import { Link } from "@tanstack/react-router";
import { useTSRBreadCrumbs } from "./use-tsr-breadcrumbs";

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/shadcn/ui/breadcrumb";
interface TSRBreadCrumbsProps {}

export function TSRBreadCrumbs({}: TSRBreadCrumbsProps) {
  const { breadcrumb_routes } = useTSRBreadCrumbs();
  if (breadcrumb_routes.length < 2) return null;
  return (
    <div className="gap-0.1 flex w-full flex-wrap p-1 px-3 md:justify-end">
      <Breadcrumb>
        <BreadcrumbList>
          {breadcrumb_routes.map((crumb) => {
            if (
              breadcrumb_routes.length - 1 ===
              breadcrumb_routes?.indexOf(crumb)
            ) {
              return (
                <BreadcrumbItem key={crumb.path}>
                  <BreadcrumbPage className="hover:text-accent-text line-clamp-1 cursor-pointer text-xs hover:max-w-fit hover:duration-300 hover:animate-in hover:fade-in">
                    {crumb.name}
                  </BreadcrumbPage>
                </BreadcrumbItem>
              );
            }
            return (
              <div className="flex items-center gap-2" key={crumb.path}>
                <BreadcrumbItem key={crumb.path}>
                  <Link
                    to={crumb.path}
                    className="hover:text-accent-text line-clamp-1 cursor-pointer text-xs hover:max-w-fit hover:duration-300 hover:animate-in hover:fade-in"
                  >
                    {crumb.name}
                  </Link>
                </BreadcrumbItem>
                <BreadcrumbSeparator className="hidden md:block" />
              </div>
            );
          })}
        </BreadcrumbList>
      </Breadcrumb>
    </div>
  );
}

[prc5]

I created these breadcrumbs for my app. They’re a bit rough and hacky, but hopefully, they’ll be helpful to you! 😄

  const matches = useRouterState({ select: (s) => s.matches });
  const router = useRouter();

  const indexRoute = {
    title: "Your app",
    pathname: "/",
  };

  const match = matches[matches.length - 1];

  const routes = useMemo(() => {
    const matched = router.flatRoutes
      .filter((route) => route.options.beforeLoad)
      .filter((route) => {
        if (route.fullPath === "/") {
          return match.fullPath === "/";
        }

        return match.fullPath.includes(route.fullPath);
      });

    return matched
      .filter((item, index) => {
        const prev = matched[index - 1];
        if (prev) {
          return prev.fullPath !== `${item.fullPath}/`;
        }
        return true;
      })
      .sort((a, b) => a.fullPath.length - b.fullPath.length);
  }, [match]);

  const breadcrumbs = useMemo(() => {
    const values = routes.map((item) => {
      const { id, fullPath, options } = item as AnyRoute;

      const context = options.beforeLoad?.();

      const title =
        id === "__root__"
          ? "Your app"
          : (context as { title?: string })?.title ||
            fullPath.split("/").join("") ||
            "Dashboard";

      return {
        title,
        pathname: fullPath,
      };
    });
    values.unshift(indexRoute);
    return values;
  }, [routes]);