Skip to main content
The PageBreadcrumbs component is used to display breadcrumb navigation at the top of your page, helping users understand their current location in your app’s hierarchy and navigate back to parent pages. 
import { PageBreadcrumbs } from "@hubspot/ui-extensions/pages";

<PageBreadcrumbs>
  <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.PageLink to="/support">Support</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.Current>Contact Us</PageBreadcrumbs.Current>
</PageBreadcrumbs>
To use this component, you’ll need to be on version 0.13.0 or later of the ui-extensions NPM package. You can check your current version by running npm list or npm list -g, and install the latest version by running npm i @hubspot/ui-extensions.

​
Basic usage

The PageBreadcrumbs component should be placed at the top of your page component, before the PageTitle. It typically contains a combination of PageBreadcrumbs.PageLink components (for navigable breadcrumbs) and a PageBreadcrumbs.Current component (for the current page). 
import { Text } from "@hubspot/ui-extensions";
import { PageBreadcrumbs, PageTitle } from "@hubspot/ui-extensions/pages";

const ContactDetailsPage = () => {
  return (
    <>
      <PageBreadcrumbs>
        <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.PageLink to="/contacts">Contacts</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.Current>Contact Details</PageBreadcrumbs.Current>
      </PageBreadcrumbs>
      <PageTitle>Contact Details</PageTitle>

      <Text>Contact information goes here...</Text>
    </>
  );
};

​
Props

​
Examples

​
Simple breadcrumb trail

import { PageBreadcrumbs } from "@hubspot/ui-extensions/pages";

<PageBreadcrumbs>
  <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.Current>Documentation</PageBreadcrumbs.Current>
</PageBreadcrumbs>

​
Multi-level breadcrumb trail

import { PageBreadcrumbs } from "@hubspot/ui-extensions/pages";

<PageBreadcrumbs>
  <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.PageLink to="/contacts">Contacts</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.PageLink to="/contacts/companies">Companies</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.Current>ACME Corporation</PageBreadcrumbs.Current>
</PageBreadcrumbs>

​
Breadcrumbs with dynamic content

import { PageBreadcrumbs, usePageRoute } from "@hubspot/ui-extensions/pages";

const ContactPage = () => {
  const { params: { contactId } } = usePageRoute();

  return (
    <>
      <PageBreadcrumbs>
        <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.PageLink to="/contacts">Contacts</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.Current>Contact {contactId}</PageBreadcrumbs.Current>
      </PageBreadcrumbs>
      <PageTitle>Contact Details</PageTitle>

      {/* Rest of page content */}
    </>
  );
};

​
Complete page example

Here’s a full example showing breadcrumbs, title, and page content together: 
import React from "react";
import { Text, Heading, Flex } from "@hubspot/ui-extensions";
import { PageBreadcrumbs, PageTitle, usePageRoute } from "@hubspot/ui-extensions/pages";

const DealNotePage = () => {
  const { params: { dealId, noteId } } = usePageRoute();

  return (
    <>
      <PageBreadcrumbs>
        <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.PageLink to="/deals">Deals</PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.PageLink to={`/deals/:dealId`} params={{ dealId }}>
          Deal {dealId}
        </PageBreadcrumbs.PageLink>
        <PageBreadcrumbs.Current>Note {noteId}</PageBreadcrumbs.Current>
      </PageBreadcrumbs>
      <PageTitle>Deal Note</PageTitle>

      <Text>Note content goes here...</Text>
    </>
  );
};
When using a layout component, you can use routeId from usePageRoute() to render different breadcrumb trails based on the active route: 
import type { ReactNode } from "react";
import { Flex } from "@hubspot/ui-extensions";
import { createPageRouter, PageRoutes, PageBreadcrumbs, PageTitle, usePageRoute } from "@hubspot/ui-extensions/pages";

const BREADCRUMBS: Record<string, ReactNode> = {
  home: <PageBreadcrumbs.Current>Home</PageBreadcrumbs.Current>,
  docs: (
    <>
      <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
      <PageBreadcrumbs.Current>Documentation</PageBreadcrumbs.Current>
    </>
  ),
  support: (
    <>
      <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
      <PageBreadcrumbs.Current>Support</PageBreadcrumbs.Current>
    </>
  ),
};

function AppLayout({ children }: { children: ReactNode }) {
  const { routeId } = usePageRoute();

  return (
    <Flex direction="column" gap="medium">
      <PageBreadcrumbs>{BREADCRUMBS[routeId]}</PageBreadcrumbs>
      {children}
    </Flex>
  );
}

const PageRouter = createPageRouter(
  <PageRoutes layoutComponent={AppLayout}>
    <PageRoutes.IndexRoute id="home" component={HomePage} />
    <PageRoutes.Route id="docs" path="/docs" component={DocsPage} />
    <PageRoutes.Route id="support" path="/support" component={SupportPage} />
  </PageRoutes>
);

​
Pattern: All links except current page

The most common pattern is to make all breadcrumb items clickable except the current page, which is displayed as plain text: 
<PageBreadcrumbs>
  <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>           {/* Clickable */}
  <PageBreadcrumbs.PageLink to="/section">Section</PageBreadcrumbs.PageLink> {/* Clickable */}
  <PageBreadcrumbs.Current>Current Page</PageBreadcrumbs.Current>                   {/* Not clickable */}
</PageBreadcrumbs>

​
Pattern: Minimal breadcrumbs

For shallow hierarchies, you might only show the home link and current page: 
<PageBreadcrumbs>
  <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.Current>Settings</PageBreadcrumbs.Current>
</PageBreadcrumbs>

​
Pattern: Resource hierarchy

Show the hierarchy when viewing a specific resource: 
<PageBreadcrumbs>
  <PageBreadcrumbs.PageLink to="/">Home</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.PageLink to="/contacts">All Contacts</PageBreadcrumbs.PageLink>
  <PageBreadcrumbs.Current>John Doe</PageBreadcrumbs.Current>
</PageBreadcrumbs>

​
Guidelines

  • DO: place PageBreadcrumbs at the top of your page component, before PageTitle.
  • DO: use PageBreadcrumbs.PageLink for all breadcrumb items except the current page.
  • DO: use PageBreadcrumbs.Current for the current page (the last breadcrumb item).
  • DO: keep breadcrumb labels concise and descriptive.
  • DO: include breadcrumbs on all pages except the home page.
  • DON’T: make the current page clickable in the breadcrumbs.
  • DON’T: create excessively deep breadcrumb trails (more than 4-5 levels).
  • DON’T: use breadcrumbs for linear processes - use step indicators instead.

​
Accessibility

The PageBreadcrumbs component automatically provides proper accessibility features:
  • Uses semantic HTML breadcrumb navigation
  • Includes proper ARIA labels for screen readers
  • Provides clear visual hierarchy
  • Supports keyboard navigation through the links
Last modified on April 14, 2026