PageBreadcrumbs

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

Prop	Type	Description

Examples

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

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

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>
    </>
  );
};

Breadcrumbs in a layout component using route IDs

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

Build apps

Add features

Publish to the HubSpot Marketplace

Skeleton group 5

Basic usage

Props

Examples

Complete page example

Pattern: All links except current page

Pattern: Resource hierarchy

Guidelines

Accessibility

​Basic usage

​Props

​Examples

​Simple breadcrumb trail

​Multi-level breadcrumb trail

​Breadcrumbs with dynamic content

​Complete page example

​Breadcrumbs in a layout component using route IDs

​Breadcrumb patterns

​Pattern: All links except current page

​Pattern: Minimal breadcrumbs

​Pattern: Resource hierarchy

​Guidelines

​Accessibility

​Related components

Basic usage

Props

Examples

Simple breadcrumb trail

Multi-level breadcrumb trail

Breadcrumbs with dynamic content

Complete page example

Breadcrumbs in a layout component using route IDs

Breadcrumb patterns

Pattern: All links except current page

Pattern: Minimal breadcrumbs

Pattern: Resource hierarchy

Guidelines

Accessibility

Related components