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?).

[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

[chorobin]

A useCrumbs hook would be implemented fairly easily with useMatches and isMatch

const useCrumbs = () => {
  return useMatches()
    .filter((match) => isMatch(match, 'context.crumb'))
    .map((match) => match.context.crumb)
}

For the moment I'm on the side of being more flexible. useCrumbs hook is very specific and I want to be open to different use cases other than breadcrumbs. useMatches and isMatch are ways to create breadcrumbs but can be used for other things.

For example, maybe you have titles which you can get from loader data. This hook builds a titles array from matches which have titles in loaderData

const useTitles = () => {
  const matches = useMatches()
  const titles = []

  for (const match of matches) {
    if (isMatch(match, 'loaderData.title') && match.loaderData?.title) {
      titles.push(match.loaderData.title)
    }
  }

  return titles
}

Simply put.

useMatches gives you a union of all possible matches

isMatch provides a way to narrow those matches, is composable and keeps the context of the match. Its possible to also grab other things from a narrowed match provided the narrowing results in a match which has it. For example if the narrowed match also has params

const useCrumbs = () => {
  return useMatches()
    .filter((match) => isMatch(match, 'context.crumb'))
    .map((match) => `${match.context.crumb} - ${match.params.postId}`)
}

You can also compose isMatch together

const useCrumbs = () => {
  return useMatches()
    .filter(
      (match) =>
        isMatch(match, 'context.crumb') && isMatch(match, 'params.postId'),
    )
    .map((match) => `${match.context.crumb} - ${match.params.postId}`)
}

[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

[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]);